In-Force Implementation Notes#
Status: Draft, 2026-11-04. ULSG_US_SEC is ULSG_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 in their grace, 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
ULSG_US_Son another time axis, and it readsULSG_US_S’s assumption tables in place, every assumption unchanged. The contractual elements are sourced from the retrieved carrier documents behind the product spec: the 25% premium load and the $5.50 monthly per-policy charge [S3] [S7], the 2.0% guaranteed credited rate [S3] [S5] [S7], the 5.0% and 3.0% loan rates [S4], the 61-day grace period [S7], the return-of-premium percentages, anniversaries and 40%-of-face cap [S1], the in-force test on the shadow account net of indebtedness [S4] [S2] [S9] and the cessation of charges at attained age 121 [S7]. Every shadow-account parameter is a std standardization: no carrier publishes them and no specimen policy form was retrievable. So are the guaranteed maximum COI curve, which is not the 2017 CSO table, the mortality table and its improvement, the lapse table, the dynamic-lapse formulas, the exercise rates and every expense. Replace them with company data before drawing any conclusion from the numbers.
Run it#
python products/guaranteed_ul/run_sec.py # point 1: the worked example, in force
python products/guaranteed_ul/run_sec.py 5 # point 5: S point 1 at 81, in its grace
python products/guaranteed_ul/run_sec.py --block # every model point, summed row by row
python products/guaranteed_ul/run_sec.py 5 --cython # point 5 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 two
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 cash flows, the two account values, the
guarantee diagnostics and the counts behind them for point 1, the technical notes’
worked-example policy. It is in force 300 months at the valuation date, as it is at the
start of ULSG_US_S’s own projection, so its rows t = 0 … 4 are the worked example’s
five months, policy months 301 to 305, here as in run.py: the account value closes them
at 7,679.31, 4,834.68 and 1,965.91, is exhausted at t = 3, and the guarantee carries the
policy from there. Its account values and guarantee diagnostics are run.py’s line for
line. Of its cash flows only expenses differ, 8.24 in the first month where run.py
prints 13.57, because the maintenance expense is in valuation-date dollars here, and
net_cf with them, −12,383.41 against −12,388.75. Three lines to the same thing for point
5:
import modelx as mx
model = mx.read_model("products/guaranteed_ul/ULSG_US_SEC")
model.Projection[4].result_guar() # point 5, the table's fifth row
Projection takes idx, the position of a point in the table, as basiclife/BasicTerm_SC
does, where ULSG_US_S takes a point_id: Projection[4] is point 5, 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 |
ULSG_US_S’s three self-checks, check_av_roll_fwd(), check_sg_roll_fwd() and
check_margin(), run over the same frame, and hold on every committed point.
--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,
pols_if the count entering each. The committed block opens with 5.43 policies, 186,024.04
of premiums and a net cash flow of 723.45. 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, wherever every frame is finite: pandas’ groupby
sum skips a NaN, and the runner’s does not, so on a frame holding a NaN or an infinity
the two can part, the runner’s sum turning NaN. The runner names a point by its label, and
maps it to its position: a label not in the table, a number or not, stops it with the
table’s labels and no traceback.
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 first month at attained age 121, where premiums and charges cease.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’duration_months + 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 inULSG_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.
ULSG_US_S already runs this policy clock, from the first month of its own projection, and
opens its in-force point there: point 1 at 300 months, with its account value, its shadow
account, its loan and its premiums to date. 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: one value more than ULSG_US_S reads, the
months it has already spent in its grace.
Point 1 is ULSG_US_S’s in-force point, in force 300 months. At t = 0 it is on the
anniversary that opens policy year 26, at attained age 85, where its 25th anniversary’s
return-of-premium window falls, and its frame has 432 rows, t = 0 … 431. Point 7 is
ULSG_US_S’s point 2 restated at its month 305, five months into policy year 26: its
policy anniversaries, and with them its annual premiums, fall at t = 7, 19, …, and its
frame has 427 rows. Point 9 is ULSG_US_S’s point 2 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, the $10,800 at the 98% premium persistency, $10,584.00,
falls at t = 25, and its frame has 757 rows.
Read on the policy clock |
Read on the valuation clock |
|---|---|
the premium months of each mode, the single premium in the issue month and the ten-pay years; acquisition in the issue month and its load on the first year’s premiums; withdrawals from policy year 2; the surrender charge by policy month; the return-of-premium windows at the 20th and 25th anniversaries; the guaranteed COI scale, the mortality rate and the corridor factor at the attained age, and the improvement rate graded by it; the base lapse rate by policy year; premiums and charges ceasing, and the projection ending, at attained age 121, policy month |
the declared credited rate, |
Expense inflation keeps ULSG_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. ULSG_US_S steps it on the policy year, from the policy’s issue, so on
a point in force it inflates the $75 a year from the issue year: point 1’s maintenance
expense is ULSG_US_S’s divided by 1.025^25, about 1.854, at every t, since both
models step on its anniversaries. Acquisition, $300 a policy in the issue month and 90% of
every first-year premium, is charged per policy issued and not inflated, as in
basiclife/BasicTerm_SE: ULSG_US_S charges it on the policies in force in the issue
month, which are the policies issued. The claim expense, $300 a death, is not inflated in
either model.
Mortality improvement runs from the start of ULSG_US_S’s own projection: the factor
is 1.0 in its first year and gains a year of improvement on each anniversary of that start,
for at most 20 years, each year’s at the rate graded at the attained age a year before,
1.0% to attained age 85 and 0 from 95. This model keeps both cells’ formulas, so
improvement runs from the valuation date, for every point of a block, which is what
ULSG_US_S already does for its own in-force point 1: the years accrue at t = 12, 24, …,
in the same months for every point, whatever its own anniversaries. Between them the factor
moves only where a graded rate it reads moves, at attained ages 85 to 95, and those step on
the policy’s anniversaries: on point 7, valued mid-year at attained age 85, it moves at
t = 12, 19, 24, 31, 36, …. A point written k months after the valuation date takes the
improvement of the valuation years before its issue too, each graded at the age its cohort
had reached in that year: point 9 dies at 0.9801 of the table’s rate in its issue month,
t = 25, where ULSG_US_S’s point 2, issued at its own t = 0, dies at the table’s rate.
So a point restated at ULSG_US_S’s month d, or written later, continues its S point
per policy, but its counts part from S’s by design: it improves from its own valuation
date, and S’s point from S’s t = 0. On the committed points the account value and the
shadow account per policy are ULSG_US_S’s exactly, while the count of point 6,
ULSG_US_S’s point 2 restated at 240, is up to 0.0271 of a policy apart and its net_cf
up to 342.78. The tests compare the counts with improvement and inflation set to 0 in both
models, and hold each of the two to the valuation clock, at its shipped value, in a test of
its own (Tests, below).
The declared credited rate is an economic input too, read at t, and ships flat at 3.50%,
so its clock shows in no number.
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
ULSG_US_S computes, whatever the point’s count. On ULSG_US_S’s three new-business
points every cash flow and every count agrees, and so does every other cell the two models
share, at every argument ULSG_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. The four cells of ULSG_US_S’s funding-premium solve are not in this model,
and compiling replaced coi_rate_scale by a schedule number, spelled status as a code and
split claims into its kinds (Departures, below). On point 1, ULSG_US_S’s in-force
point, which both models open at the valuation date, the projection is ULSG_US_S’s from t = 0 on, in every cell the two share but inflation_factor and the cells it reaches, the
expenses, the expense margin, net_cf and result_cf(); with inflation set to 0 in both,
every cell agrees.
The in-force interface#
The model point table is model_point_table_sec.csv. It carries ULSG_US_S’s columns,
pols_if_init renamed policy_count, and seven of its columns are the in-force interface:
basiclife/BasicTerm_SE’s two, and five that open an in-force policy’s state. Every amount
is per policy.
Column |
Unit |
Measured at |
Meaning |
|---|---|---|---|
|
policies, not necessarily whole |
for a point in force, the start of month 0, before any month-0 event; for any other, its issue month |
the policies in force at the valuation date, for a point already in force; the policies issued, for one issued at or after it |
|
whole months |
the valuation date |
the policy’s age in months: positive in force, in any month of its policy year, 0 for a policy issued at the valuation date, |
|
dollars, 0 or more |
the start of month 0, before any month-0 event: the close of policy month |
the account value, its loaned part included |
|
dollars, of either sign |
the start of month 0 |
the shadow account, which is never floored: below 0 it measures the catch-up shortfall |
|
dollars |
the start of month 0 |
the policy loan outstanding, the interest accrued to then included |
|
dollars |
the start of month 0 |
the premiums paid from issue to policy month |
|
whole months, an int |
the start of month 0: the counter after policy month |
the months already spent in the grace period, 0 for a policy not in grace; at most |
The five state columns are 0 on a point issued at or after the valuation date: it is issued
with no account value, no shadow account, no loan, nothing paid and no grace.
av_pp_init, sg_pp_init, loan_bal_init and cum_prem_init are ULSG_US_S’s own
columns, and the technical notes’ av_init, sg_init, loan_init and cumprem_init:
they already measure the balances entering ULSG_US_S’s first month, so they keep their
names. grace_mth_init is named for the cell it opens, grace_mth, as they are for
theirs; the technical notes give the counter no model point attribute, and open it at 0.
The shadow account is state, carried in its own column like the account value: it is the
policy’s own balance, not a path a model could recompute from issue.
UL_US_SEC’s other state columns would open no cell here. The face never moves, since a
withdrawal reduces the two accounts and not the face, and the product has neither a free
withdrawal allowance nor a 7-pay test, which the notes put out of the model: so there is no
sum_assured_init, wd_used_year_init or is_mec_init. Nor is there a loan account, as
in VUL_US_SEC: the loaned part of the account value is the debt itself. 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 |
|
— |
|
|
On the twins the new column takes what ULSG_US_S itself assumes, 0, so each twin opens as
its S row does: point 1 with the worked example’s account value of 2,400.00, shadow account
of 118,000.00, no loan, 270,000.00 of premiums paid, 25 annual premiums of $10,800, and no
grace.
The columns carried over are read as ULSG_US_S reads them. For a policy in force, the
facts they record are still those at issue, the mode and the withdrawal excepted:
Column |
Unit |
Measured at |
|---|---|---|
|
labels |
— |
|
years, age nearest birthday |
issue, not the valuation date: |
|
codes, as in |
issue |
|
dollars of face |
issue: the face, level for the life of the policy, on which the per-unit charges and the surrender charge are quoted |
|
an attained age, 90 to 121 |
the guarantee elected at issue; 121, the lifetime election, sets the lifetime lapse multiplier |
|
|
the pattern over the frame: a single premium falls in the issue month alone, ten-pay’s in the first ten policy years |
|
dollars a year, the scheduled premium, or the single premium on |
issue: the premium the policy was issued on, which a point in force goes on paying |
|
|
the mode over the frame; its instalments fall on the policy clock |
|
a fraction of each premium |
the base premium load, contractual |
|
a probability, or blank |
a pin of the point, which holds in every month (below) |
|
decimal places, or blank |
a pin of the point, which holds in every month (below) |
|
dollars a month |
the withdrawal taken in every month of cover from policy year 2; 0 on every shipped point |
|
a flag and a schedule ID, a row of |
issue |
|
a flag |
whether the return-of-premium endorsement applies |
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.
The premium is an input. It is fixed at issue, and a policy in force goes on paying
the premium it was issued on, whatever its shadow account now stands at: so the model reads
it from premium_pp_ann, as basiclife/BasicTerm_SE reads its premium from a table.
ULSG_US_S’s funding-premium solve, which finds the level premium that keeps the guarantee
in force from issue, stays ULSG_US_S’s (Departures, below). On its point 2 it finds
10,803.93, where the column holds the technical notes’ P*, 10,800.00.
The two pins, prem_persistency_override and coi_rate_dp, are rules of the point,
not state, and ULSG_US_S applies each in every month of its frame. So does this model,
and a point restated in force or written later keeps its S point’s pins. Point 1 and point
5, the worked-example policy restated 81 months on, pin both: the premium persistency at
1.00 and the declared COI scales to 2 decimals per $1,000, which reconciles the notes’
worked example with their own factor rule. Every other committed point leaves both blank,
and takes the 98% persistency of a level payer and the scales at full precision.
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, and so is every column of
ULSG_US_S’s own that the projection reads as a number or a flag:age_at_entry,sum_assured,guarantee_age,premium_pp_ann,wd_pp,load_prem_rate, the two pins,has_surr_chargeandrop_elected: “model_point_table_sec.csv has no grace_mth_init column”;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,356 months at issue age 18, the youngest the product issues, and 1,032 at 45, the youngest the shipped COI scale serves. Set to 0, the Reference refuses future new business altogether, and a negative horizon is itself refused;age_at_entryandguarantee_ageare each a whole number of years, 0 or more: the projection takes theint()of each, whereULSG_US_Swould truncate a guarantee age of 95.5 to 95;sum_assuredis a number above 0, the face every policy holds, and each ofpremium_pp_annandwd_ppa number, zero or more;load_prem_rate, the share of each premium the load takes, 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]”. Past 1 the account would be credited a net premium below 0, which the account value’s floor at zero absorbs: at a load of 1.5ULSG_US_S’s account-value and margin checks fail on each of its points;prem_persistency_overrideis blank, where the point takes the rule, or a number from 0 to 1, a probability, andcoi_rate_dpis blank, where the point quotes its scales exact, or a whole number of decimal places, 0 or more, whereULSG_US_Swould take theint()of 2.5;has_surr_chargeandrop_electedare eachTrueorFalse, as pandas reads those words, in any case, so thatTRUE,falseandFaLsEdecode, and project, asTrueandFalsedo. A blank, a number, 1, 0, 1.0 and 0.0 among them, or any other text is refused: one such value turns the whole column into text, where"False"and"0"are true strings, so that every point would read as carrying the flag;av_pp_initis a number, zero or more. A balance is never negative in force.ULSG_US_Slets the account value close a month below zero with a loan on an exhausted account, through the loaned part’s lower credited rate, so the message says what to do: restate such a point no later than the last month its account value is still zero or more;sg_pp_initis a number, of either sign: the shadow account is never floored;loan_bal_initandcum_prem_initare each a number, zero or more;grace_mth_initis a whole number of months, 0 or more;a policy not yet in force,
duration_mth0 or less, has an opening state of zeros: “model_point_table_sec.csv: grace_mth_init must be 0 on a policy not yet in force, duration_mth 0 or less; it is not at point_id [9]”.
The text columns, sex, rate_class, premium_type, premium_mode and
surr_charge_id, are keys and codes, which the projection decodes or joins on at their
first read, as ULSG_US_S does: a pattern or a mode no decode knows raises ULSG_US_S’s
message, and a class or a schedule its table lacks raises at its first read. The grace
counter is not held to the account value: ULSG_US_S can carry a positive account value
in grace, once the loaned part earns more than the unloaned, so no such rule could be
right.
Three kinds of point read, but proj_len() refuses each, naming the point, because each
is a rule of the product, read from Projection’s References, not the table’s. It checks
them in this order:
a point to be issued at or past attained age 121, which would never be in cover: “point_id 9: age_at_entry 121 is at or past charges_cease_age, 121: a policy issued there would never be in cover”. The age is checked first, so that a point issued past it within a year, whose frame would also end before the valuation date, is refused by its age, not by a policy month below 0. A point to be issued at attained age 120 is a policy, with a year of cover;
a point at or past the end of the projection at the valuation date,
duration_mth ≥ 12 × (121 − age_at_entry): “point_id 3: duration_mth 732 is at or past the end of the projection, policy month 732, attained age 121”;a point whose grace expired before the valuation date,
grace_mth_init ≥ grace_months: “point_id 5: grace_mth_init 2 is at or past grace_months, 2: the grace expired before the valuation date, so the policy lapsed then, with no value”. A policy whose grace has expired lapsed at the start of the next month, with nothing to pay, and is not in force, and the in-force interface carries no lapse latch.
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 or its count from. The tables read at an attained age or a
policy year take their extents from corridor_age_first() and corridor_age_last(),
mort_age_first() and mort_age_last(), lapse_last_year() and, for coi_rates.csv,
whose sex and rate class cells are numbered as schedules, coi_schedules(), which checks
the table, and coi_rate_last_ages(), the last attained age of each schedule, beyond which
each reads its nearest row. The COI scale is clamped at its last age alone, as in
ULSG_US_S: an attained age below its cell’s first raises at the first read. 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 an age or a year, 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”, and, inside a cell of the COI scale, “coi_rates.csv: the ages of each sex
and rate_class must run one row an age, without a gap or a repeat; at (‘M’, ‘StdNT’), no
line holds age 61”. So is a blank sex or class in the COI scale, and a value 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: “mort_table.csv: mort_rate must be
a number from 0 to 1; it is not on line [44]”. A class factor, a guaranteed COI rate and a
surrender charge are held to 0 or more, since below it each projects negative deaths, a
credit for the insurance or a surrender charge that rises once its schedule has run off.
A COI rate is a charge per $1,000 of net amount at risk a year, not a decrement: the
shipped scale is above 1 at every age it charges and 0 at 121, where charges cease, and the
current monthly rate passes 1 from attained age 69, as it should. A corridor factor is held
to 0 or more too, a multiple of the account value that the statute’s applicable
percentages hold to 100% or more: one below 1 only makes the corridor bind later, and one
below 0 would leave db_pp’s floor on the account value the one thing between an account
below 0 and a death benefit above the face. 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. surr_charge_count() also
refuses a run-off that is not a whole number of years, 1 or more, which the projection
divides the charge by, where ULSG_US_S divides by zero at 0: “surr_charge_table.csv:
runoff_years must be a whole number of years, 1 or more; it is not on line [2]”.
rop_count() checks the return-of-premium windows, which are read by membership of their
anniversaries: an anniversary that is blank, text, not a whole number of years, 1 or more,
or on two rows, is refused, and so is a refund ratio or an exercise rate outside 0 to 1.
Each reader asks for its extent or its count before it reads a value, so a projection meets
the checks first. ULSG_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 or age 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 lapse rate
reaches the lapse rate’s floor and is read as it, 0.3%, a blank corridor factor reads as no
corridor, a blank surrender charge as none, and a blank COI rate reaches the account
value’s floor at zero, which reads it as an exhausted account. Here the cap on the
mortality rate, min(q, 1.0), keeps a blank base rate or class factor missing, as
ULSG_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
ULSG_US_S and its table by tests/sec_support.py, from the ULSG_US_SEC entry in its
SEC_SPECS, and the tests regenerate the table and compare, so an edit to a ULSG_US_S
row reaches it or fails the suite. In the source repository,
python tools/gen_sec_points.py ULSG_US_SEC writes it.
Point |
Kind |
From |
At the valuation date |
|---|---|---|---|
1 |
twin |
S point 1 |
the technical notes’ worked-example policy, in force 300 months, on the anniversary opening policy year 26, at attained age 85, with 2,400.00 of account value, a shadow account of 118,000.00 and 270,000.00 of premiums paid: its |
2–4 |
twin |
S points 2–4 |
issued at |
5 |
derived |
S point 1 at S month 81 |
a month into its grace, in force 381 months, at attained age 91, with 0.428726 in force, no account value, a shadow account of −1,365.21 and a grace counter of 1: it lapses at |
6 |
derived |
S point 2 at S month 240 |
on its 20th anniversary, whose 50% window falls at |
7 |
derived |
S point 2 at S month 305 |
five months into policy year 26, at attained age 85, its account value exhausted and the guarantee carrying it on a shadow account of 244,383.19: its anniversaries fall at |
8 |
derived |
S point 3 at S month 731 |
its last covered month, at attained age 120, with 4.012e-10 of a policy: a one-row frame, whose |
9 |
future |
S point 2, 25 months on |
to be issued at |
A derived row’s policy_count is the count ULSG_US_S carries into that month, its
pols_if(d), and its opening state is what ULSG_US_S carries into it, each column read as
ULSG_US_S’s own formulas read it: the account value as av_pp_at(d, "BEF_PREM"), the
shadow account as sg_pp_at(d, "BEF_PREM"), the loan as loan_bal_pp_at(d, "BEF_INT"), the
premiums to date as cum_prem_pp(d − 1) and the grace counter as grace_mth(d − 1). So the
row continues the S projection from there, per policy: point 5 opens with 0.428726 policies,
and point 8 with 4.012e-10. A month by which ULSG_US_S has lapsed the policy cannot be
restated, since no policy is in force there to restate: the generator refuses it, naming
the point and the month (The opening state, below). Each pin is the S point’s. A derived
row’s policy_id is the S row’s with the month appended, GUL-000001-M81, and a future
row’s carries the months to issue, GUL-000002-F25. Row t of a generated point is month
t + source_mth of its S point. All nine are on the anchor cell M60 / StdNT / $500,000,
because the illustrative COI scale covers that cell alone, from attained age 45, so a point
on any other sex or class, or issued younger than 45, 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 ULSG_US_S already names, each an int Reference named as the string
ULSG_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, or 0 once the policy has lapsed for insufficiency;BEF_DECR = 1, that count pluspols_new_biz(t), before montht’s decrements;BEF_MAT = 2, the count before any maturity,ULSG_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 accounts’ six and the loan’s one among them, which follow in
the same numbering, BEF_PREM = 3 to BEF_INT = 9 (The compiled model, below).
ULSG_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 ULSG_US_S counts the issued policies, and this model counts them as new
business, not yet in. As in UL_US_SEC and VUL_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 month’s decrements are ULSG_US_S’s, in its order, all at the end of the month: deaths,
then surrenders out of the survivors, then return-of-premium exercises out of those left,
and, in the month before a grace expires, every policy still left, pols_lapse_grace(t),
which terminates with no value. The lapse latch, is_lapsed(t), then shuts from the next
month, and the count is 0 from there.
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 four decrements in ULSG_US_S’s order. Each account’s
opening balance forms the previous month’s close the same way, the same operations in the
same order as the closing cell ULSG_US_S calls for: av_pp_at(t, BEF_PREM) from its own
value at t − 1 and month t − 1’s net premium, withdrawal and fee, expense charges, cost
of insurance, zero floor and interest, where ULSG_US_S’s account value ran through six
cells a month; sg_pp_at(t, BEF_PREM) likewise, where ULSG_US_S’s shadow account ran
through six; and loan_bal_pp_at(t, BEF_INT), a month’s interest on its own value at
t − 1, where ULSG_US_S’s loan ran through two. The premiums to date call themselves at
t − 1, and the grace counter and its latch are one chain between them, as in
ULSG_US_S. The mortality improvement factor reads itself a year back, a chain of one cell
a year: past 20 years, from t = 252 on, it is the factor of month 240, so it is at most 22
cells deep.
On a model just read, a cold net_cf in the last month of point 1’s 432-month frame runs
447 cells deep, against 2,111 for ULSG_US_S’s point 1: 16 cells above the chain back to
t_entry(). The other committed points run 15 to 18 above theirs: 747 cells on points 2,
3, 4 and 9, each on the books for 732 months. At the longest cover the contract allows,
issue age 18 and 1,236 months, it runs 1,253 deep at the valuation date and 1,256 issued
120 months after it, 18 and 21 above the chain: every chain stops at the issue month, but in
its first month the mortality of a point issued later reads the improvement factor of the
valuation years before its issue. Compiled, that call runs on the C stack (What a
compiled run needs, below). Each chain’s head called alone, on a read of its own with
every chain cold, the loan’s, the premiums’, the account value’s, the shadow account’s, the
grace counter’s with its latch and the count’s, runs at most 12 cells above its chain on
the committed points, the count’s the deepest, which runs 14 above at the longest cover at
the valuation date and 17 issued 120 months on; the improvement factor asked alone runs at
most 27 levels, from t = 252 on. 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 ULSG_US_S’s under 14. A point issued 120 months on
needs 19, since its first month reads the improvement factor of the ten years before it.
Exported by modelx, with the recursion limit set after the import, the cold net_cf of the
last month needs a limit of 918 on point 1, 1,518 on points 3 and 9, and 2,526 at the
longest cover, issued now or 120 months on, and the ascending sweep 58, against 3,929 to
5,977 and 52 for ULSG_US_S’s points.
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 ULSG_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_rop(t) + pols_lapse_grace(t) + pols_maturity(t)
at every t of every frame, the month of a lapse and every month after it included, 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) < charges_cease_mth(), where
charges_cease_mth() = 12 × (charges_cease_age − age_at_entry) is ULSG_US_S’s frame from
issue, the first month at attained age 121. Outside it, before issue and from
t = proj_len() on, every count, balance, premium, withdrawal, charge, decrement rate,
decrement, claim and cash flow is zero and every flag false, the grace counter and the
return-of-premium anniversary are the int 0, and status says why: PRE_ISSUE before
issue and CEASED from t = proj_len() on. Only the two clocks, the inputs read on the
valuation clock and the dynamic lapse multiplier’s neutral 1.0 hold values there, and the
month after the frame holds three exceptions more, below. No count evaluates a decrement
rate there, and no table is read at a policy year, an attained age or an anniversary the
policy does not have: sum_assured_at, prem_persistency, premium_pp, cum_prem_pp,
wd_pp, corridor_factor, db_pp, coi_rate_guar, coi_pp, sg_coi_pp, maint_fee_pp,
sg_maint_fee_pp, the timings of the two accounts and the loan, surr_charge_rate,
mort_rate, lapse_rate_base, lapse_rate, the four decrements and expenses are zero,
is_premium_mth false and grace_mth and rop_anniversary 0, before any table or rate is
read, and every other value is zero through them. lapse_rate_dyn_mult is 1.0 there,
before it reads the guarantee or the account value. Each table read at a policy year, an
attained age or an anniversary 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 60. The mortality improvement rate is the one cell read at an
attained age before issue, on a point written later, and it reads no table: it grades the
improvement of the valuation years before issue at the age the cohort has reached in each.
The end of the projection. The frame ends at charges_cease_mth() because premiums and
charges cease at attained age 121, not at an event of the contract, whose cover continues
there [S7]. The shipped mortality table reaches 1.0 at attained age 120, but improvement
takes the rate below it: on a point issued at or after the valuation date at attained age
60, 20 years of 1% leave the rate at attained age 120 at 0.817907, and on point 1, whose
years of improvement fall from attained age 85 on, at 0.946302. So lives can survive the
last month, and ULSG_US_S’s roll-forwards read them: check_av_roll_fwd() and
av_change() read the account value in force entering month t + 1, and
pols_lapse_grace() the lapse latch of month t + 1, which in the last month is
t = proj_len(). So the three opening values read there, the count carried in
(pols_if_at(t, BEF_NB), and through it pols_if(t)), the account value carried in
(av_pp_at(t, BEF_PREM)) and the latch (is_lapsed(t)), are defined for
0 ≤ duration_mth(t) ≤ charges_cease_mth(): in the month after the frame they are the
survivors of the last month, the account value they carry and the latch the last month
leaves, ULSG_US_S’s own values there. Everything else is zero or false there, the shadow
account included, which no cell reads there, and the expenses, which would otherwise fall
on the carried count. Nothing reads past it: av_change(), pols_lapse_grace() 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 3.48e-10 of a policy on
the twin of point 3, ULSG_US_S’s own, and 0.0 on every other committed point: points 1,
2, 4, 5, 6, 7 and 9 lapse before the end, and point 8, whose improvement restarts at its
valuation date, dies in its one month at the table’s 1.0.
Rates stay rates. The annual mortality rate is capped at 1.0, as in ULSG_US_S,
min(q, 1.0) with its bound second, so that a missing input stays missing. On no committed
point does the product pass 1, since all are on StdNT, whose factor is 1.0: the cap binds
on the tobacco classes, whose factors take the table past 1, first on StdTob at attained
age 107, 1.75 × 0.582849, at an A/E of 1.0 with improvement off.
The annual lapse rate keeps ULSG_US_S’s floor of 0.3% and cap of 50%, each bound written
first, min(lapse_rate_cap, max(lapse_rate_floor, rate)), and Data holds each base rate
to 0 to 1, so the rate stays a probability while lapse_rate_cap is at most 1. On the
committed points the rate before its bounds is at most 0.04, so the cap never binds there,
while the floor binds from policy year 21 on, where the base rate is 0.75% and the
multipliers take it below 0.3%.
The opening state#
ULSG_US_S opens its in-force point 1 from four columns, the account value, the shadow
account, the loan and the premiums to date entering its first month, and reads the grace
counter of the month before its frame as 0. The worked example’s policy is not in grace at
its policy month 300, so point 1 needs no more, and its twin opens the same way. A policy
valued in any month of its life needs all five columns, each what ULSG_US_S carries into
that month. The committed points show what each changes, each compared with the same row
read with the column at what ULSG_US_S assumes or at 0, or, for the shadow account,
floored at zero as the account value is:
grace_mth_init. Point 5 isULSG_US_S’s point 1 a month into its grace, at its month 81. It carries a counter of 1, which its first month, whose deduction fails again, advances to 2: the grace has run its two months, every policy left at the end of month 0, 0.423179 of them, terminates, andpols_if(1)is 0.0, asULSG_US_S’spols_if(82)is. Read with the counter at 0, asULSG_US_Sreads the month before its frame, the grace would open afresh att = 0and the policy would lapse a month late, with 0.423179 policies still in force att = 1.sg_pp_init. The same row’s shadow account is −1,365.21, below zero: the guarantee has failed, and the negative balance is the catch-up shortfall. Month 0’s charges take it to −5,551.43, so the catch-up premium that would restore the guarantee is 6,034.16. Floored at zero, as the account value is, the shadow account would close month 0 at −4,180.11 and the catch-up premium would be 4,543.60.cum_prem_init. Point 1 has paid 25 annual premiums of $10,800, 270,000.00, and its 25th anniversary’s window falls att = 0: the refund there is the premiums paid, month 0’s included, 280,800.00, capped at 40% of the face, 200,000.00, so the 0.099303 of a policy that exercises is paid 19,860.68 andnet_cf(0)is −12,383.41. With the column at 0 the refund would be month 0’s premium alone, 10,800.00, the refunds 1,072.48 andnet_cf(0)6,404.80. Point 6, on its 20th anniversary, has paid 211,680.00, and its 50% window refunds 111,132.00 a policy att = 0; with the column at 0 it would refund 5,292.00.av_pp_init. Point 6 also holds 911.21 of account value entering month 0, so that the account closes the month at 7,098.16, the cash surrender value of a policy that surrenders then, where read as 0 it would close at 6,181.24.
loan_bal_init is 0 on every committed point, as on every point of ULSG_US_S’s. A loan is
read where ULSG_US_S reads it: the loaned part of the account value earns the loan credit
rate, both of the guarantee’s tests net it, and every claim deducts it.
A row in its grace, and none after a lapse. At the shipped assumptions ULSG_US_S’s
point 1 exhausts its account at its month 3, the guarantee carries it through month 79,
its grace opens at 80, and it lapses at the start of 82, with no value:
S month |
|
|
|
|
|
|---|---|---|---|---|---|
79 |
0.439333 |
0 |
|
6,871.71 |
|
80 |
0.434093 |
1 |
|
2,779.48 |
|
81 |
0.428726 |
2 |
|
−1,365.21 |
|
82 |
0.0 |
0 |
|
−5,551.43 |
|
83 |
0.0 |
0 |
|
−9,756.36 |
|
A row restated at 80 carries a counter of 0, and one at 81 the counter of 1 that point 5
carries, ULSG_US_S’s grace_mth(80); each lapses where ULSG_US_S does, at t = 2 and
t = 1. No row is restated at 82 or later. The policy has lapsed: ULSG_US_S’s count there
is 0 and its latch shut, and the in-force interface carries no latch, since a lapsed policy
is not in force. So the generator refuses every month by which ULSG_US_S has lapsed the
policy, naming the point and the month, and proj_len() refuses a hand-made row whose
counter is at or past grace_months, as a row at 82 would carry 2. A row at 83 would carry
a count of 0 and a counter of 0, since ULSG_US_S’s counter reads 0 once the policy has
lapsed, and the model’s rules accept that as a point with no policy in force: so it is the
generator, which reads ULSG_US_S’s latch, that refuses it. Points 2 and 4 lapse at their
months 504 and 236, and the last months each can be restated at, in its grace with a
counter of 1, are 503 and 235.
A counter carried in resets where ULSG_US_S’s does, in the first month whose deduction no
longer fails: a grace can end without a lapse where a scheduled premium falls due and
carries the deduction. ULSG_US_S’s point 4 paying $6,150 a year, a variant the tests use,
enters its grace at its month 239, and the anniversary premium at 240 cures it. Restated at
240 with a counter of 1, it resets at t = 0 and stays in force; restated at 243, where its
second grace is a month old, it lapses at t = 1. With improvement and inflation set to 0
in both models, each is ULSG_US_S’s projection from there, cell by cell.
Departures from ULSG_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, an attained age or an
anniversary answers for the months outside cover. Of ULSG_US_S’s 139 cells in
Projection, 55 are unchanged, 34 have a new docstring only, most of them to say what t
now counts, and 46 are rewritten; four, the funding-premium solve, are removed, none is
renamed, and 25 cells are new, 160 in all. A cell of ULSG_US_S’s that this model lacked
would fail the twin identity, which names each of the four with its reason. ULSG_US_S’s
References solve_tol, solve_max_doublings and math, which only the solve and the
checks’ math.isclose read, are dropped. Of Data’s nine cells, model_point_table is
rewritten to check the table as it reads it, three readers have their read_csv call
wrapped and mort_table its docstring; nine cells are new, 18 in all, and so is the
Reference future_horizon_mth, 120. Compiling then changed how each cell reads its inputs
and spells its codes, and no number (The compiled model, below): in Projection it
replaced one cell, coi_rate_scale, by a schedule number, and added five more, 165 in all;
of ULSG_US_S’s cells it changed the signature of one, claims, and the type of one,
status, which returns a code. The twin identity exempts coi_rate_scale and status,
each with its reason, and compares ULSG_US_S’s claims(t, None) with the total
claims(t). In Data it rewrote coi_rate_last_ages, a Series at stage E, as an array
checked by the new coi_schedules(), and added 38 cells, 56 in all, and widened the checks
of the model point table and of the three age tables. The cap on mortality, min(..., 1.0),
is ULSG_US_S’s own and no departure, and so are the shadow account never floored, the
lapse rate’s two bounds in ULSG_US_S’s order and improvement from the start of the
projection, which here is the valuation date.
Cells |
|
|
Why |
|---|---|---|---|
|
|
|
|
|
a recursion from |
|
Policies in force at the valuation date open the count; new business joins it in its issue month; the chain is one cell a month |
|
|
the same openings at |
Every chain one cell a month, since a compiled model runs it on the C stack |
|
opened at |
opened at |
A policy in force brings in its premiums to date and the months it has spent in grace; a policy that has lapsed is not in force |
|
branches on the text of |
branches on three decodes, |
No projection cell reads text, and none calls a label accessor. The label accessors stay, for reporting, and a value no decode knows still raises |
|
the model point’s |
read once a point: the pin 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. |
|
joined on the label accessors; the point’s COI scale a Series, sliced from the table by its sex and class |
the class factor joined to the points in |
A blank factor, a missing value to |
|
the table read in the monthly cell, at |
one reader keyed by the age or the year — |
No table is read at an age or a year the policy does not have, each is read once an age or a year, and a blank, text or fractional key, keys that repeat or leave a gap, a value that is not a number, a lapse or mortality rate outside 0 to 1 and a corridor factor or a COI rate below 0 are refused by name, where |
|
the schedule’s row read in the cell |
|
The same numbers on any schedule, with no table read in a monthly cell; a blank charge, which |
|
the return-of-premium table read in each |
three readers keyed by the anniversary, |
No monthly cell reads a table; an anniversary that is not a whole number of years, 1 or more, or is on two rows, and a refund ratio or an exercise rate outside 0 to 1 are refused |
|
unguarded: no |
zero, false or the int 0 outside cover, |
A future point’s months before issue have |
|
|
zero outside cover |
At |
|
the text |
a code: |
Codes for the months outside cover, which |
|
|
|
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 |
|
the funding-premium solve, a bisection over the level premium of a replay of the shadow account |
removed |
The premium is an input fixed at issue (below) |
|
|
|
A compiled cell takes C numbers, and |
|
|
the same, with the divisor checked first and Python’s error raised, |
Compiled C’s division raises the same error with another message. |
|
a malformed value or key met, if at all, only when a projection reaches it, a missing class, scale or schedule as |
refused by name at the first read of the array, over the whole table: a class, a sex and class or, on a point with a charge, a schedule the tables lack; an issue age, a guarantee 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 are policy_count, t_entry, is_active, pols_new_biz,
grace_mth_init, the new opening-state accessor, and coi_rate_last_age, the extent of a
point’s COI scale; those of compiling are listed under What compiling changed, and why,
below.
The funding-premium solve is not in this model. ULSG_US_S implements the technical
notes’ complete algorithm, a bisection over the level annual premium of a replay of the
shadow account with decrements off, as a side calculation that nothing in its projection
reads, and its tests check it. It is an issue-time calculation: it finds the premium a
policy is issued on, and a point in force carries that premium from issue, in its
premium_pp_ann. So this model reads the premium from the column, and the solve stays
ULSG_US_S’s. Kept unchanged here, the solve would answer a question no point valued later
asks. It replays the shadow account from the frame’s first month, not from the policy’s
issue, so on a point in force it solves from the valuation date: 11,961.02 on point 6, which
was issued on 10,800.00 and is still paying it, and 31,033.42 on point 1, from its shadow
account of 118,000.00 at month 300, as ULSG_US_S finds on its own point 1. On a point
written later, whose months before issue enter its minimum at zero, it finds no premium at
all and raises. And its cells take the premium as a float argument, which a compiled model
could cache only in a Python dictionary. To solve a policy’s premium from a later state,
give ULSG_US_S a point carrying that state, as its point 1 does: it solves from that
point’s own start.
Of the cash flows, the change of clock moves the maintenance expense, and net_cf with it,
and on a point restated or written later, through mortality improvement, the counts and
every flow they weight. Point 1’s expenses(t) less its claim expense is ULSG_US_S’s
divided by 1.025^25 at every t. Point 9’s maintenance expense is 1.025^2 above
ULSG_US_S’s point 2’s, month for month, and 1.025^3 in the last month of each policy
year, where the valuation year has stepped and the policy year has not; its acquisition,
9,825.60 a policy, is ULSG_US_S’s exactly.
The compiled model#
The model compiles under modelx-cython into C-typed code, as basiclife/BasicTerm_SC does,
and modelx reads and runs the same formulas as before. Compiling changed how each cell
reads its inputs and spells its codes, and no number: what the model computed on each
committed point was frozen before the change, and it still computes it (Tests, below).
Cell by cell, at every argument a full modelx sweep evaluates, the compiled model computes
what modelx computes, bit for bit, on the committed points; 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 guaranteed_ul # in place, beside the model
python tools/build_sec_cy.py guaranteed_ul --out /tmp/ulsg # elsewhere, with the CSVs
The tool exports the model to ULSG_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 ULSG_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/guaranteed_ul") # the directory holding the build
from ULSG_US_SEC_nomx_cy import mx_model as model
model.Projection[4].result_guar() # point 5, 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 = 4 after Projection.result_cf() leaves point
1’s 432-row frame cached, while point_id(), not yet computed, reads point 5’s label, and
Projection.inflation_rate set to 0 once Projection[5] has computed point 6’s
expenses(12) leaves it at 4.2441, where modelx recomputes 4.1580. Set every Reference on
a model just imported, before anything is computed, where modelx would recompute.
A build takes about two minutes with gcc, 129 s here under load, 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 148 of its 160 Projection cells as C numbers, but eight of them still took a timing
or a kind as text, or claims’s None, and so kept a dictionary for a cache, as did
status, which returned text; and it ran only 2.2 to 2.5 times its own export, 10.4 to
10.8 ms a point on net_cf against 23.7 to 27.2, over the committed points. The bodies of
the typed cells still called pandas and Python: a model_point() lookup for each of the 22
columns a formula read, a .loc on a table for each attained age’s corridor factor,
mortality and COI rate, each policy year’s lapse rate, each anniversary’s refund ratio and
exercise rate and each point’s class factor and surrender-charge schedule, the point’s COI
scale sliced into a Series by its sex and class, pd.isna on the two pins, text compared
in every formula that branched on the premium pattern or the mode, and a generator summed
in claims. So each input now reaches a cell as a number:
idx.Projectionis parameterized by the position of a point in the table, from 0, asBasicTerm_SCis:Projection[4]is point 5, 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 a formula branches on, for every point at once: the premium pattern intois_level_premium,is_single_premiumandis_ten_pay_premium, the premium mode intopremium_freq, its payments a year, andhas_surr_chargeandrop_electedinto flags of their own. Each decodes asULSG_US_Scompares the column, exactly, so a value none of the flags names is no flag, and a mode none of the frequencies names is 0, and the cell that branches on it raisesULSG_US_S’s message, asULSG_US_Sdoes, where it is read: a SINGLE point, which never reads its mode, projects whatever it is. The two pins become numbers: the persistency pin a value, NaN where blank, and a flag of whether the point gives one, and the COI precision an int, −1 where blank,ULSG_US_S’s own “exact”.Tables indexed by integers. The lapse table is 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 return-of-premium windows are held by anniversary, from 0 to the last, a flag of membership and the two values, so that the anniversary is the index. The COI scales, keyed by sex and class, 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 attained age incoi_rate_array, padded from age 0, with the first and last age of each schedule beside it,coi_rate_first_agesandcoi_rate_last_ages: the plan’s R7, asTerm_US_SEC’s tables are held. The padding holds NaN, and nothing reads it: each table’s one reader refuses a policy year below 1 or an age below a COI scale’s first, naming the point, reads an age outside the corridor or mortality table at its nearest row, asULSG_US_Sdoes, and answers an anniversary outside the windows’ range as in none. The class factor and the surrender-charge schedule are one number a point, and each is joined to the points inData. Every point reads its class factor and its COI scale in its first month in cover, and a point with a charge its schedule in every month of it, soDatarefuses a class, a sex and class or, on a point with a charge, a schedule the table lacks, naming every such point, whereULSG_US_SraisedKeyErroras the point projected: every projection for the first two, and for a missing schedule the point’s cash flows and margin check, which read it (its counts, accounts and guarantee report do not). Compiled, that refusal is the table’s, so every point with a charge is refused those two reports with it, asTerm_US_SEC’s refusals at the first read are. A point without a charge is never refused a projection for its schedule, whichULSG_US_Snever reads; it reads its schedule’s two columns where the table holds its ID, as at stage E, and where the table does not,has_surr_charge_schedule()is 0 and both accessors raiseKeyError, naming the point, where their.locraised it at stage E.Codes. A timing, a kind or a status, which
ULSG_US_Sspells as text, is an int Reference named as the text: the count’s timingsBEF_NB = 0,BEF_DECR = 1andBEF_MAT = 2, the accounts’BEF_PREM = 3,BEF_WD = 4,BEF_FEE = 5,BEF_COI = 6,BEF_INV = 7andEOM = 8, and the loan’sBEF_INT = 9; the kindsDEATH = 0,LAPSE = 1,REFUND = 2,GRACE = 3,WITHDRAWAL = 4andMATURITY = 5; and the statusesPRE_ISSUE = 0,IN_FORCE = 1,IN_FORCE_GUARANTEE = 2,GRACE = 3,LAPSED = 4andCEASED = 5. A call reads as before, less the quotes:pols_if_at(t, BEF_DECR),av_pp_at(t, BEF_COI),loan_bal_pp_at(t, BEF_INT),claim_pp(t, DEATH). A string argument or a string value would give the cell a dictionary for a cache, where a code indexes a C array, so codes are numbered from 0 without a gap. The model has three families of timing, the count’s, the two accounts’ and the loan’s, passed to different cells, and they are numbered as one,BEF_NBandBEF_DECRfirst, as in every SEC model, then the count’s third, then the accounts’ in the order of their instants within the month,EOMlast, then the loan’s. So no two timings share a code, and a code of one family passed to another’s cell,av_pp_at(t, BEF_NB)orloan_bal_pp_at(t, BEF_PREM), is refused asinvalid timingin both engines, where families numbered each from 0 would read it as a timing of the cell’s own without a word.ULSG_US_Sspells a kind and a status alike,"GRACE", and the two families are numbered so that it is 3 in both, one Reference. Two of its statuses are not names,"IN FORCE"and"IN FORCE - GUARANTEE": their codes join the words with underscores, the hyphen dropped, andresult_av()writesULSG_US_S’s label for each code in itsstatuscolumn, so the report reads asULSG_US_S’s. TheProjectiondocstring’s Codes lists all 21.The claims, split, and their total compensated.
ULSG_US_S’sclaims(t, kind=None)is one kind’s claims or, withNone, its four kinds summed by a generator: neither a C parameter nor a C loop. Here the three kinds that pay are cells,claims_death,claims_lapseandclaims_refund, theresult_cfcolumns, andclaims(t)is their total; the fourth,GRACE, is 0.0 in every month, a policy terminating in grace terminating without value, and has no cell. Python’ssumof floats is compensated, since Python 3.12: it carries the rounding error of each addition, Neumaier’s way, and adds it back once at the end. On a return-of-premium anniversary deaths, surrenders and refunds all pay in one month, and there a total written left to right,0.0 + d + l + r, differs fromULSG_US_S’s in the last bit in 3 of the 8 such months of the committed points. Soclaims(t)issum’s loop written out, each addition and its carried error in explicit statements, which compile to C, and its last test, that the carried error is finite, writtenabs(c) <= 1.7976931348623157e308, the largest double, which no compiler folds away. The total isULSG_US_S’s float in every month.One 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, andround.coi_rateandsg_coi_ratehold the declared COI scales to the point’s precision withround(r, dp), asULSG_US_Sdoes, whereris aProjectionReference,coi_curr_factororcoi_sg_factor, times the guaranteed rate.Datacannot read aProjectionReference, so the rounding cannot be done there ahead of the projection, as the plan’s R16 would have it, without moving the two factors out ofProjectionor freezing them. So the call stays, a call into the interpreter on the same double in both engines, made only on a point that pins its precision, points 1 and 5 of the committed table, andtests/us_registry.pyadmits it in those two cells alone, as it admitsWholeLife_US_SEC’sround. The one division whose divisorULSG_US_S’s own inputs can make zero,cure_premium_pp’s at a load of 1, is guarded, and raises Python’s ownZeroDivisionError: float division by zero, where compiled C’s division would raise the same error with another message (What it refuses, below).Reporting cells stay Python.
model_point(), the label accessorssex(),rate_class(),premium_type(),premium_mode()andsurr_charge_id(), and the four reports return a table row, text and DataFrames, for a reader, forrun_sec.pyand for the comparison withULSG_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 blankpremium_modeon a SINGLE point, which never reads its mode, and a column of numbers, ints. 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 and arrays, each with the column or file it comes
from: 17 vectors of int64, among them the point labels, the decodes, the COI schedule of
each point and the first and last age of each schedule; 18 vectors of float64, among
them the joins and the five arrays of the tables by age, year or anniversary; the COI
scales by
schedule and age; and ten int counts and extents, each a table’s check, coi_schedules,
the COI table’s, which at stage E returned a Series of last ages, among them. The nine
readers stay Python, returning DataFrames and a path, and no Projection cell but
model_point() reads them. Every other cell of Projection, 155 of its 165, 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,358 by |
the 97 cells of |
a C array of 1,358 by 10 |
|
a C array of 105 by |
|
a C array of 122 by |
|
one |
the 44 cells without a parameter but the reporting ones: the point’s label, numbers, decodes and pins, its opening state, its class factor, COI schedule and the scale’s first and last age, its surrender charge and run-off, the ends of its frame, the monthly guaranteed, shadow and loan rates and the two NAAR factors, the lapse rate’s guarantee and pattern factors, and the three checks |
a Python object |
|
The declarations the build generates, _mx_classes.pxd in the compiled package, are the
record of it, and none of Projection’s caches there is a dictionary.
The sample and the spec#
mx2cy types each cell from the values the sample run passes it and gets back, and a cell
the run never calls compiles as a Python object. So sample_sec.py runs the four reports
and the three checks on every committed point, which reach 157 of the 165 cells, and then
the eight they do not and the eight codes no formula passes: model_point() and the five
label accessors, which only a reader asks for; point_id(), which only a refusal names;
cure_premium_pp, the payment that would cure a grace, which no report reads; and, in
cells the reports reach, pols_if_at at BEF_MAT, av_at at BEF_WD, BEF_FEE,
BEF_COI, BEF_INV and EOM, claim_pp at GRACE, and claims_from_av at
WITHDRAWAL and MATURITY. It calls the monthly ones in every month of the frame and the
month after it. 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 five 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: withdrawals, the TEN_PAY pattern, the
non-annual modes, a single premium’s lapse factor, the corridor binding, the lapse rate’s
cap, the cap on mortality and a loan. 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. The two
round calls are reached on points 1 and 5, which pin the precision. 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,358 |
1,356. The longest frame is a policy issued at the youngest issue age, 18, to the end of the projection at attained age 121, 103 policy years, and issued 120 months after the valuation date, the furthest ahead |
|
1,358 by 10 |
|
|
1,358 by 10 |
|
|
105 |
103, the policy year of the last covered month at issue age 18, read by |
|
122 |
120, the last attained age in cover, read by the three readers by age inside cover alone, from the youngest issue age, 18 |
proj_len() refuses a point issued below 18, issue_age_min, and one issued at or past
charges_cease_age, 121, in modelx as compiled, and the projection ends at attained age
121, so no report on a point the model projects runs past these caches. Those two
References and Data.future_horizon_mth are the contract the sizes are derived from.
Lower the minimum, or raise charges_cease_age or the horizon, and a report runs past the
caches in the compiled model alone: a frame of more than 1,357 months, a policy year or an
anniversary past 104 or an age past 121 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 × (charges_cease_age − issue_age_min) + the horizon + 2, y
to charges_cease_age − issue_age_min + 2, and a to charges_cease_age + 1. The
shipped COI scale carries the anchor cell alone, from attained age 45, so a point at any
other cell is refused by Data, and one issued below 45 by its first COI rate, naming it;
an issue age of 18 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 eight powers: the monthly rates of both
decrements, 1 − (1 − q)^(1/12) in mort_rate_mth and lapse_rate_mth, the monthly
credited, guaranteed, shadow, loan and loan-credit rates, (1 + i)^(1/12) − 1 in
inv_return_mth, guar_rate_mth, sg_rate_mth, loan_rate_mth and loan_cr_rate_mth,
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 2,699,256
bytes, about 2.7 MB, the type’s basic size, which holds every cell’s cache: 97 arrays of
1,358 months and seven of 1,358 by 10, each beside a flag array of its shape that marks
what is computed, make most of it, the seven 2-D caches’ values 760 KB of it. That is 1.4
times UL_US_SEC’s, for 2-D caches ten wide against eight, seven of them against five,
and more cells a month. 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
1,298 MB (Speed, below). Allocating and zeroing the struct is paid once a point:
the frame pass, which makes each point’s ItemSpace, asks its proj_len() and releases it,
took about 0.1 ms a point (Speed).
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 18, issued now or 120 months
on, runs the account value’s chain back to t_entry(), 1,253 and 1,256 cells deep in
modelx (Counts and timings, above), and compiled with gcc it runs on a thread of 320 KiB
of stack and not of 288, 235 to 262 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 then it
is an estimate: at WholeLife_US_SEC’s 325 to 433 bytes a level it would be about 400 to
530 KiB, inside 1 MiB by about twice. A stack below the need kills its child on an
overflow, by design (with gcc, 288 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,526 there, and the four
reports and the three checks, which run in ascending t, need 58 once the package is
imported and 128 with its import, as the sample runs them, so sample_sec.py sets 11,000,
four times the first rounded up to the thousand, and a test holds it to that derivation.
On Windows, which no run here has reached, the cython CI job’s Windows leg is the
check, and five things are particular to it. The stack, above, is MSVC’s to measure. The
claims total is exact only where the compiler neither folds 0.0 + x away nor fuses an
addition with a multiplication: gcc is held to that by -ffp-contract=off, and MSVC’s
default, /fp:precise, keeps both, on x86-64, whose SSE2 arithmetic has no fused
multiply-add; the finiteness test, abs(c) <= 1.7976931348623157e308, is one no compiler
folds. The powers call the C runtime’s pow, which modelx’s float power calls too, on
the same platform, and round is the same Python call in both engines, so the compile
tests’ exact comparison holds there too, and a difference would be a finding. MSVC
accepts the unpickle code’s mismatched 2-D cache shapes that gcc 14 refuses, so the one
inner width is held by the Linux leg and by the test of the spec’s sizes. And the cost
of allocating and zeroing the 2.7 MB struct a point has been measured on Linux alone.
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,model_point_table_sec.csv: point_id must be a whole number; [1.5] is not, when the labels are first read, bypoint_id()or a refusal; arate_classthe class factors lack,class_factor_table.csv has no factor for the rate_class of point_id [2]; a sex and rate class the COI scale lacks,coi_rates.csv has no scale for the sex and rate_class of point_id [2, 6]; 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.ULSG_US_Sfails every projection of a point of the first two kinds with aKeyError, and of the third its cash flows and margin check, which read the schedule (its counts, accounts and guarantee report do not); compiled, the third refusal is the table’s, so every point with a charge is refused those two reports with it, asTerm_US_SEC’s refusals at the first read are. No projection of a point without a charge reads its schedule, so none is refused for it; on such a pointsurr_charge_rate_max()andsurr_charge_runoff_years()raiseKeyError,'point_id 2: surr_charge_table.csv has no schedule for its surr_charge_id', compiled as in modelx. Every decode and join compares the text exactly, asULSG_US_Sdoes, so"StdNT ", with a space, is no class. And, before it is cast to int64, a number of2**53or more in size, which numpy would cast to the least int64 without a word: apoint_id, an issue age,model_point_table_sec.csv: age_at_entry must be below 2**53 in size, where an int64 holds it; it is not at point_id [3], a guarantee age, aduration_mth, a policy issued2**63months on, a grace counter and a COI precision, whichULSG_US_Sprojects as exact. The five columns are the model point table’s rule 19, checked after its other 18, so that each of those keeps its message, and a fractional issue age is refused by the earlier rule that it be a whole number of years; thepoint_idis refused when the labels are first read.A negative age in
corridor_factors.csv,mort_table.csvorcoi_rates.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 refusalULSG_US_Slacks, checked after the table’s other rules, so that a table whose ages leave a gap keeps that message.A key beyond a table, by the one cell that reads it, naming the point, where
ULSG_US_S’s lookup raisedKeyError: a policy year below 1,point_id 2: lapse_table.csv has no rate for policy year 0, fromlapse_rate_base_py; an attained age below the point’s COI scale,point_id 2: coi_rates.csv has no rate for the point's sex and rate_class at attained age 40, fromcoi_rate_guar_at, which a point issued at 40 meets in its first month in cover; and an anniversary without a window,point_id 2: rop_table.csv has no anniversary 3, fromrop_ratio_annivandrop_rate_anniv, none of which a projection calls outside cover or off a window.By
proj_len(), a point to be issued at or past attained age 121, at or past the end of the projection, whose grace has expired, or issued belowissue_age_min, in that order, the lastpoint_id 2: issue age 17 is below issue_age_min, 18(The in-force interface, above, quotes the others).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 another family,av_pp_at(0, BEF_NB),loan_bal_pp_at(0, BEF_PREM),pols_if_at(0, BEF_PREM),av_at(0, BEF_MAT),sg_pp_at(0, BEF_INT), a timing of the family a cell lacks,av_pp_at(0, EOM), a kind a cell lacks,claim_pp(0, MATURITY), and a code up to 9,claims_from_av(0, 9).A mode or a pattern no decode knows,
ValueError("invalid premium mode")andValueError("invalid premium type"), where the point reads it, as inULSG_US_S.At a load of 1,
cure_premium_pp’sZeroDivisionError: float division by zero, whichULSG_US_Sraises there too.Dataadmits the load, asULSG_US_Sprojects it, since no report reads the cure payment.
An argument outside a cache raises IndexError in the compiled model alone, as above:
net_cf(1358), which modelx answers with 0, the month being outside cover;
pols_if_at(0, 10) and claim_pp(0, 10), which modelx refuses as invalid timing and
invalid kind; lapse_rate_base_py(105), which modelx reads at the table’s last year,
0.0075, and lapse_rate_base_py(-1), which modelx refuses, naming the year;
corridor_factor_at(122) and corridor_factor_at(-1), which modelx reads at the table’s
nearest row, 1.00 and 2.50; coi_rate_guar_at(122), which modelx reads at the scale’s
last age, 0.0; and is_rop_anniv(105) and is_rop_anniv(-1), which modelx answers
False. 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, charges_cease_age,
lifetime_guarantee_age, wd_first_year, ten_pay_years, grace_months, the
improvement’s ages and years, the codes and idx a long long, as
Data.future_horizon_mth is, 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, charges_cease_age = 121.7 reading 121
and issue_age_min = 18.5 reading 18, where modelx computes with the float:
charges_cease_age = 121.0 makes charges_cease_mth() a float there, and result_cf()
then fails. A text, a NaN 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: crediting_rate_curr = 0 gives
crediting_rate_ann(0) 0 in modelx and 0.0 compiled, and so does wd_fee in wd_fee_pp,
which 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; and load_prem_rate_sg set to 1,
which catch_up_prem_pp divides by 1 − load_prem_rate_sg, raises ZeroDivisionError
in both, with float division by zero in modelx and Cython’s shorter float division
compiled. That divisor is a Reference, which a user sets on purpose, not a model point
value, and it is not guarded.
A rate past its domain is computed, not refused, as in ULSG_US_S. The annual mortality
rate is capped at 1, min(q, 1.0), in both, so its monthly rate stays real. The lapse
rate is held between lapse_rate_floor and lapse_rate_cap, and with a bound set past 1
the annual rate passes 1 and the monthly rate, 1 − (1 − w)^(1/12), has no real value: it
is complex in modelx, whose account value and margin checks then raise TypeError, and
NaN compiled, whose same two checks then fail, a residual that is not a number failing,
while the shadow account’s, which no decrement reads, holds in both. A NaN rate stays NaN
through the cap on mortality, 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) NaN in both.
Data’s refusals of a value outside its range keep any NaN from reaching them through
the inputs.
A withdrawal or a loan on a policy whose account the guarantee holds at 0 is accepted and
projected, as ULSG_US_S projects it, and fails two checks in both models, whatever its
size: on point 7, valued with its account exhausted, a withdrawal of $1 a month or a loan
of $1,000 makes check_av_roll_fwd() and check_margin() false, compiled as in modelx,
while check_sg_roll_fwd() holds. ULSG_US_S pays a withdrawal whatever the account can
fund, and accrues a loan the account cannot carry, and compiling moves no number, so
neither model changes; it is an item for ULSG_US_S (USLIB-SEC-PLAN.md §7.5).
Speed#
python tools/bench_sec_cy.py guaranteed_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 |
1.42 ms (8.55–9.10) |
2.13 ms (12.80–13.58) |
87 MB |
export |
603 |
17.4 ms (10.47–11.15) |
16.8 ms (10.12–11.97) |
87 MB |
modelx |
126 |
539 ms (67.9–70.1) |
551 ms (69.4–72.3) |
181 MB |
The blocks are the committed table repeated, 667 times compiled, 67 exported and 14 in
modelx. On net_cf the compiled model runs 12.2 times its export, and on result_cf, where
building the DataFrame takes much of its time, 7.9 times; it runs 380 and 259 times modelx.
A second run of the compiled model and the export straight after, under a 1-minute load
between 2.5 and 3.0, gave the compiled model 1.43 and 2.13 ms and the export 16.8 and 16.8
ms, 11.8 and 7.9 times. That is about as many times its export as UL_US_SEC, 12.0, and
WholeLife_US_SEC, 13.9, and more than Term_US_SEC, 9.5, or BasicTerm_SC on its own
measure, 8.7. A point takes longer than UL_US_SEC’s, 1.21 ms, for 165 cells against 136
and a struct 1.4 times the size. As it stood after running in force, compiled the same way,
the model ran 2.2 to 2.5 times its export (What compiling changed, and why, above), and
the compiled model runs about seven times that build on the same measure, 1.43 to 1.68 ms a
point over the committed points against 10.41 to 10.84: the representation, not the
compiler, is the gain. 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 1,298 MB. Reading the eight files and
building every Data vector and array for those points took 0.073 s, and asking every point
for its frame, the runner’s first pass, which makes, reads and releases each point’s
ItemSpace, 0.58 s, about 0.1 ms 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 2.3 and 3.1 as the runs started; Linux, Python 3.13.18 and gcc 13.3.0, with modelx 0.33.0, modelx-cython 0.1.0, Cython 3.3.0, numpy 2.5.3 and pandas 3.0.5. Under load the spread is wide, and the fastest run is the one to compare.
Tests#
The twin identity, in
tests/test_model_conventions.py: on points 2, 3 and 4, issued at the valuation date, every cell ofULSG_US_S’s agrees at every argumentULSG_US_Sevaluates in its own sweep, but forpols_if_init,model_pointandresult_pols, whose meaning changed, the four cells of the funding-premium solve, which this model does not have,coi_rate_scale, the point’s COI scale as a Series, which this model replaced by a schedule number, and whose rates the identity compares incoi_rate_guarin every month, andstatus, a code here, whose labels it compares inresult_av’sstatuscolumn;ULSG_US_S’sclaims(t, None)is compared with the totalclaims(t), and its kinds through theresult_cfcolumns. A cell this model lacked, or that took other arguments, would fail it otherwise. The identity holds on any count, sinceULSG_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 twin, in
tests/test_guaranteed_ul_us_sec.py: point 1 opens withULSG_US_S’s own opening balances and no grace, and with expense inflation set to 0 in both models it isULSG_US_S’s projection fromt = 0, in every cell and every report, to 1e-9 relative with no absolute floor; at the shipped assumptions the two part in the maintenance expense alone, in the inflation factor, the expenses, the expense margin and the net cash flow, and in no other cell. So the goldenstests/test_guaranteed_ul_us.pyasserts on point 1 — every cell of the worked example’s five rows, the notes’ NAAR constants, the account value’s exhaustion att = 3and the guarantee carrying the policy fromt = 4— hold here, with no number restated.The splice: each
ULSG_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 two accounts at every timing, the loan, the grace counter, the latch and the checks’ verdicts among them, to 1e-9 relative with no absolute floor, since its counts fall far below 1e-7. It leaves out those the twin identity skips andULSG_US_S’s own opening values and frame. The months straddle the product’s events: the first anniversaries; the surrender charge’s last month; the account’s exhaustion under the guarantee; a grace that opens in the valuation month, and a counter carried into it, which lapses the policy a month on; the 20th and 25th anniversaries’ windows, att = 0and, on a row valued mid-year, att = 1; the month the shadow account’s net amount at risk is floored; and the last covered month, whoset = 1is the month the survivors are carried into. So are 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: ten-pay premiums, quarterly; withdrawals that outrun an exhausted account, semi-annually; a loan under a funded account, in force at 300; a loan of $10,000 on S point 1’s exhausted account, in force at 300, which takes the account entering 65 of its months below 0 and decides the guarantee’s test in two, so that its twin and its row restated at 3, the last month its account is still 0 or more, compareULSG_US_Swhere the loan’s credit and the guarantee’s test both read the debt; a single premium large enough for the corridor to bind, on a COI scale that stops short of its cover, so that its later ages are read at its last; a guarantee to 99, monthly, with neither a surrender charge nor the endorsement; each pin alone; issue age 40, below the mortality table’s first age, on a second surrender-charge schedule; S point 4 paying $6,150 a year, whose anniversary premium cures its grace; S point 2 paying $100 a year, too little for its first month’s deductions, issued 13 months on, the one row in grace from its issue month, which reads the grace counter’s base there; and S point 2 with a guarantee to 100, the lifetime guarantee’s age the splice sets, met exactly, where the guarantee to 99 meets it a year short. Between them they carry both sexes and every class. The twin of each variant issued at the valuation date is compared with its S point cell by cell, as a row issued there is, so that an issue rule only a variant takes att = 0is reached; the two variants of point 1, in force 300 months, are splice cases fromt = 0, as point 1 is. The References are set in both models: expense inflation and mortality improvement at 0, the two inputs on the valuation clock that move a number; the mortality A/E at 0.56, which leaves survivors at the end of every frame that does not lapse; a premium tax of 2%, the one assumption the product ships at zero; and the lifetime guarantee’s age at 100 and the single premium’s lapse factor at 0.65, each set apart from the Reference it ships equal to,charges_cease_age’s 121 and the dynamic lapse multiplier’s 0.6, so that a cell reading the one for the other shows. A second fixture, on References of its own, binds the two boundsULSG_US_Sships idle, the lapse rate’s cap, lowered to 1.25%, and the credited rate’s floor, under a declared rate of 1.5%. Charges cannot cease in cover, since the frame ends where they do.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 line of the model the full grid reaches, every opening-state column, every kind of valuation month, every premium pattern and mode, and every floor and cap the grid binds, each checked by the raw value it bounds, and a test asserts that they do. It also records each side of every
minandmaxthe core’s rows bind, by the values each call compares, and asserts that every side binds there but the seven bound by tests of their own: the two boundsULSG_US_Sships idle, on the second fixture; the cap on mortality; the three clamps of the tables shorter than the cover; and the shadow account residual’s floor of 1, where its sides are small. The other cases carry thesec_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.Future new business: issued 1, 12, 13 and 25 months after the valuation date, S point 2 is the S projection moved on, cell by cell, and so are S points 3 and 4 and each new-business variant issued 13 months on, whose months before issue reach policy year −1; with zeros before issue in every report and no decrement rate evaluated there.
How it computes: each row the splice and the future business compare is first run on the books and scanned: no cell has been called at a negative month, none evaluated from
t_entry()on has read a month before it but the mortality improvement factor, which on a point written later reads the valuation years before its issue, by design, and none evaluated at monththas read a month later thant + 1. Every monthly cell holds its value outside cover and reads no table there, before issue and atproj_len(), on the committed points and on the splice. 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, no projection cell has read a label accessor, and the solve’s cells are absent. And every chain is called cold, each call on a read of its own:net_cfin the last month on the committed points, and each chain’s head on the twin of point 3, and both on the two rows of the longest cover, one issued now and one 120 months on, whose frames are asserted first, modelx’s stack trace counting no more than one cell a month back tot_entry()and a fixed overhead, which a chain of two cells a month would exceed, while the improvement factor stays within a bound of its own; the ascending sweep at the longest cover belongs to the full grid.Counts, validation and regeneration: the roll-forward closes, the month of a lapse and the last month included,
BEF_MATis theBEF_DECRcount, andpols_if_atrefuses a timing it does not have;result_pols()isULSG_US_S’s, column for column, withpols_new_bizbeside it; multiplyingpolicy_countby 2.5, with every assumption that ships at zero switched on, scales every counted cell 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, a flag written 1, 0, 1.0 or 0.0 among them; a flag writtenTrueorFalsein any case decodes, and projects, as written; 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 value outside its range, a corridor factor below 0 among them, while the bounds of each range are read; apremium_typeorpremium_modeno decode knows raisesULSG_US_S’s message; the horizon is a Reference, which at 0 refuses any future business, saying so; a point to be issued at or past attained age 121, one at or past the end of the projection and one whose grace has expired are refused byproj_len(), in that order, a counter atgrace_monthsand one past it among them, and withgrace_monthsmoved to 3 a counter of 3 is refused and one of 2 projects, and a point issued at attained age 120 has a year of cover; every stateULSG_US_Sreaches on either splice’s inputs, restated in force by the generator at the edges of its windows, or withUSLIB_SEC_FULL=1at every month before its lapse, is read byDataand has a frame, but the one it refuses by name, an account value below 0 under a loan on an exhausted account, which also failsULSG_US_S’s own checks; the edges of the interface are accepted, the keys of every keyed table and the integer columns written as floats among them; the committed table is whatULSG_US_Sgenerates, and the generator refuses a month after a lapse; and each committed derived and future row opens withULSG_US_S’s own count and state at its month and continues its S point per policy, frame by frame, at the shipped assumptions.The opening state and the rest: point 5 opens from its own grace counter and shadow account, and the twin of point 1 from its own premiums to date, and read as
ULSG_US_Swould open them they give the numbers above; mortality improvement, expense inflation and the declared rate run on the valuation clock, the improvement 0.9801 in point 9’s issue month; a check whose residual is not a number fails, the NaN sent through a Reference the counts read, the improvement rate, and through two that reach a residual without them, the declared rate and the shadow account’s rate, and each check decides asULSG_US_S’smath.isclosedoes where its sides fall below 1; a lapse rate past 1, under a cap raised past it, makes the account value’s and the margin’s checks raise in both models, the residuals being floats; on a point whose loan comes to exceed its cash value the margin identity holds whereULSG_US_S’s fails; acquisition falls on new business alone, per policy issued and not inflated; a StdTob point at an A/E of 1.0 with improvement off, whose product first passes 1 at attained age 107, isULSG_US_S’s in every cell, the capped months included, as new business and restated in force, 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 A/E or the improvement rate, each a Reference, and so does one that reaches a bound written second; a corridor table cut to ages 61 to 94 and a mortality table ended at 110, each read past its ends at its nearest row, leave two variantsULSG_US_S’s points in every cell, each clamp binding with an effect; each pin holds in every month and alone; the premium is the column’s, and the solve isULSG_US_S’s; the docstrings describe this model and notULSG_US_S, their tables read into the right cells, and they parse under docutils with nothing rendered wrongly; both models read the one copy of each assumption table, and every other Reference of either Space isULSG_US_S’s, value for value, but the horizon this model adds and the solve’s tolerance, its limit of doublings and themathmodule, which it leaves out with the solve; the grace’s length, which ships equal to the failed guarantee’s lapse multiplier, 2, is set apart from it at three months, and the twins ofULSG_US_S’s points 1, 2 and 4 are its points then, each through its lapse, a month later; 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.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 its reports, 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 ULSG_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, a kind or a status, and the three claims cells forclaims(t, kind). The extract is relabelled rather than numbered by position, and each point is named by its label, inpoint_id(), in a refusal and inrun_sec.py’s output.What compiling changed: the claims total is
ULSG_US_S’sclaims(t)bit for bit, sign of a zero and type included, on every month of the committed points, the months where three kinds pay among them, and on totals set in both models where a sum written left to right would differ; each code is the Reference the Codes table names, the three timing families numbered as one,GRACE3 as a kind and as a status, andstatusholdsULSG_US_S’s labels throughresult_av; the spec’s sizes are those derived from the contract, and the sample’s recursion limit the one derived from the export’s need; the padding beyond each table’s extent is NaN, and the persistency pin NaN exactly where the column is blank; a point issued belowissue_age_minis refused byproj_len(), naming it, and the longest frame, issue age 18 issued 120 months on, is 1,356 months; each number read into an int64 at2**53or more, and a negative age in an age table, is refused, and the class and COI joins and the charged schedule refuse a key their table lacks, naming every point, while a point without a charge is not refused for its schedule, reads it where the table holds its ID, as at stage E, and raisesKeyErrorwhere it does not; a mode or a pattern no decode knows raisesULSG_US_S’s message where it is read, and a SINGLE point projects whatever its mode; andrun_sec.py --cythonprints whatrun_sec.pyprints, and outside the repository says it cannot build. Each is a test oftests/test_guaranteed_ul_us_sec.py’s Stage EC section, run in modelx with no compiler:test_the_claims_total_is_s_sum_bit_for_bit, on the twins’ every month and on the eight committed months where all three kinds pay, three of which a total written left to right gets wrong, andtest_the_claims_total_sums_any_parts_as_s_sum_does, on three negative zeros and on1e16, 1.0, -1e16;test_the_codes_are_dense_and_grace_is_one_codeandtest_status_is_a_code_and_the_report_keeps_s_labels;test_the_spec_sizes_each_cache_as_its_comment_derivesandtest_the_sample_raises_the_recursion_limit_its_comment_derives;test_every_padded_array_holds_nan_and_no_reader_reads_it, eight refusals below a table on an extract labelled otherwise than by position;test_the_coi_schedules_are_numbered_by_key_whatever_the_file_order, six scales written in reverse key order;test_what_data_cannot_number_or_join_is_refused_naming_it, seven cases;test_a_value_no_decode_knows_is_refused_as_in_ulsg_us_s, eighteen, each value a decode or a join names in another case and with a space beside it;test_a_point_without_a_charge_reads_its_schedule_as_at_stage_e, on SC7, a second schedule, onGUL15and on an ID no table has, each pinned to the value the model read at stage E;test_a_point_issued_below_issue_age_min_is_refused_by_proj_len; five cases of the int64 bound among the malformed rows and three negative ages among the malformed keys; and the two runner tests. Beside the pins’ test,test_the_precision_pin_at_0_and_blank_is_s_pin_cell_by_cellcompares the twins ofULSG_US_S’s point 2 at 0 places and blank withULSG_US_S, cell by cell, and holdscoi_rate_dp()toULSG_US_S’s int, so that 0 read as exact, or the accessor’sint()dropped, fails there.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 One Python call kept, and the registry admitsroundincoi_rateandsg_coi_ratealone; everyDatavector a formula reads is an int64 or float64 array, read by element; no cell is uncached; and each label accessor returns its point’s column of the same name.Compiled, where modelx-cython and a C compiler are installed, after compiling the model once into a temporary directory, never into the tree. In the same conventions module: the generated declarations give every cell but the reporting ones a C
bint,long longordoubleand a C-array cache of exactly the spec’s size, and every newDatacell but a reader a typed memoryview or a C scalar, and the generated C keeps no Python object among a projection cell’s locals, calls no Python builtin there but the admittedround, 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_guaranteed_ul_us_sec.py, eleven compiled tests after the fingerprint: the same comparison on the splice grid, the core by default and the full grid withUSLIB_SEC_FULL=1, variants included, ten rows at a time, with the timings and kinds no sweep reaches called too, and every compiledclaims(t)held to thesumof its compiled kinds byfloat.hex, the sign of a zero included, which the comparison by value cannot see; at the contract’s extremes, seven points, the longest frame, 1,356 months from issue age 18 issued 120 months on, ten-pay quarterly with withdrawals, StdTob at 85 where the cap binds, a one-row frame, issue age 120 and a load of 1, on a COI copy written in reverse key order and a return-of-premium table with anniversaries 1 and 102; four cases of labels that are not text, blank or numeric; the keys of every table written as floats; where the cap binds, and under five References at NaN; the compiled model refuses what modelx refuses, with modelx’s message, in 243 cases on their own inputs, the compiledDatacell beside the projection, and thirteen arguments past a cache raiseIndexError; on points without a charge, the two schedule accessors read the stage E values, and raiseKeyErroron an ID the table lacks, as modelx does, andData’s joins are modelx’s arrays; 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 it ran on, 384 KiB with gcc; past a lapse rate of 1 the compiled checks fail where modelx’s raise; 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 with no build. Under load, with the build reused, the grid took 74 s on the core grid, the refusals 140 s, the cap’s 29 s, the labels’ 21 s and the extremes’ 14 s. 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_guaranteed_ul_us_sec.py -q
USLIB_SEC_FULL=1 python -m pytest tests/test_guaranteed_ul_us_sec.py -q # the full grid
python -m pytest tests/test_model_conventions.py -q -k ULSG_US_SEC
python -m pytest tests/test_compiled_conventions.py -q -k ULSG_US_SEC
python -m pytest tests/test_guaranteed_ul_us_sec.py -q -m cython # the compiled tests