In-Force Implementation Notes#
Status: Draft, 2026-11-02. SPIA_US_SEC is SPIA_US_S taught to project
from a valuation date. Besides annuities whose annuity date is that date, it takes
contracts already in payment there, and annuities commencing 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
SPIA_US_Son another time axis, and it readsSPIA_US_S’s assumption tables in place, every assumption unchanged. The contractual elements — the five payout forms, the two survivor-reduction triggers, the fixed compound COLA, the cash-refund and installment-refund definitions and the commutation surrender-charge scale — are sourced from the composite’s product documents [S1] [S2] [S3] [S5]. Everything else is a std standardization, among them the mortality table and the improvement scale, which are illustrative stand-ins for the 2012 IAM Basic table and Projection Scale G2, the expense and commutation assumptions, and the initial incomeB(1), which is an exogenous input because no insurer publishes payout factors. Replace them with company data and a real quote before drawing any conclusion from the numbers.
Run it#
python products/immediate_annuity/run_sec.py # point 1: the anchor cell
python products/immediate_annuity/run_sec.py 16 # the anchor in payment 14 months
python products/immediate_annuity/run_sec.py --block # every model point, summed
python products/immediate_annuity/run_sec.py 16 --cython # point 16 on the compiled model
--cython runs the compiled model and prints the same lines. The runner builds it beside
the model with the repository’s tools/build_sec_cy.py the first time, in about a minute,
and again whenever the model, sample_sec.py, spec_sec.py or the tool is newer than the
build, and says so on stderr. --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 the fifteen rows run.py prints for SPIA_US_S’s point 1, the worked
example’s anchor cell commencing at the valuation date, every column the same, with the
counts, survival and payment factors behind them. The second prints the same cell in
payment 14 months, the month after its joint annuitant’s death. It pays 343.33 a month from
t = 0, two thirds of the 515.00 the COLA has reached, as SPIA_US_S pays in its month
14, and 353.63 from t = 10, its second anniversary. Its expenses are in valuation-date
dollars, 5.00 a month where SPIA_US_S’s month 14 carries 5.125, a year’s inflation more,
and liability_cf and net_cf move with them. Three lines to the same thing for point 16:
import modelx as mx
model = mx.read_model("products/immediate_annuity/SPIA_US_SEC")
model.Projection[15].result_cf() # point 16, the table's sixteenth row
Projection takes idx, the position of a point in the table, as basiclife/BasicTerm_SC
does: Projection[15] is point 16, and its point_id() says so. result_cf() has
SPIA_US_S’s seven columns — pols_if, annuity_payments, claims, commutations,
expenses, and the gross outgo under both signs, liability_cf and net_cf — with one row
per month from the valuation date, t = 0 … proj_len() − 1. result_pols() sets out what
lies behind it on the same rows: pols_if and pols_new_biz, the annuities commencing in
the month, then SPIA_US_S’s survival and payment-factor columns in SPIA_US_S’s order,
the survival read at the end of each month, and every column 0 before an annuity commences.
--block asks every point for its frame before it projects any, then projects each and
releases its ItemSpace once its frame is read, so the run holds the cells of one point at
a time. Deleting it, del model.Projection[idx], is not enough: an ItemSpace sits in
reference cycles, which only Python’s cyclic collector frees, so the runner collects after
each release. It freezes everything alive (gc.freeze()) once the model and its table are
read, and again once it has asked every point for its frame, so that each collection scans
only what the block has made since. It keeps the block’s sum as it goes, compensated as
pandas sums a groupby, so that the block is, bit for bit, the frames concatenated and
summed by t, as below. The shipped table is a set of test cases standing at different
calendar dates (Two clocks, below), so the block shows how the frames add, and nothing
more.
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 long the contract has been in payment, monthtruns from timetto timet + 1, and the frame runst = 0 … proj_len() − 1, whereproj_len()is the number of months from the valuation date to the stop rule. Survival is indexed by a time point on this clock:lives_if(t, life)andlives_if_last(t)are survival at timet, the start of montht, so the deaths of monthtarelives_if(t, life) − lives_if(t + 1, life)and an arrears instalment is paid on survival to timet + 1, as inSPIA_US_S.SPIA_US_Scalls that argumentk, on its one clock; here it ist, because survival is carried forward from the valuation date.duration_mth(t), the policy clock, counts the months elapsed from the annuity date at the start of montht:duration_mth(t) = duration_mth_init() + t, withduration_mth_init()read from the model point. It is the technical notes’ month index, and the contract runs on it:duration(t) = duration_mth(t) // 12,policy_year(t) = duration(t) + 1andage(t, life) = age_at_entry(life) + duration(t), as inSPIA_US_S, and through them the payment months, the COLA anniversaries, the certain period, the commutation months and the surrender-charge year. A cell keyed on this clock takesk, a policy month or the time point that opens it, ory, a policy year:is_payment_pm(k)andannuity_pp_sched_pm(k)are the payment schedule by policy month,annual_income(y)the income by policy year, andcum_annuity_pp(k), the notes’G(k), the instalments scheduled before the timekmonths after the annuity date, so the notes’G(13)reads as they write it. The two table readers,mort_rate_base_at(x, life)andimprovement_rate_at(x, life), take an attained age,x.BasicTerm_SEreaches the policy clock by adding one a month, a recursion as long as the frame; the closed form needs no such chain of calls.
The stop rule ends every frame where it ends SPIA_US_S’s. stop_mth() is
SPIA_US_S’s frame length from the annuity date, max(horizon_mths(), certain_mths_eff()):
the notes’ age stop on the youngest covered life, or the end of the certain period if that
is later. A month is in the contract’s frame when 0 ≤ duration_mth(t) < stop_mth(),
which is is_active(t), and the frame ends with the last such month,
proj_len() = stop_mth() − duration_mth_init(). A contract’s own end, its last death or
its last certain instalment, is a probability or a floor reaching zero inside the frame,
which runs on with zeros, as SPIA_US_S’s does.
Point 16 is the worked example’s anchor cell in payment 14 months. At t = 0 it is in
policy year 2, at attained ages 66 and 63, and its joint annuitant has been dead since the
end of policy month 13, the worked example’s month of death. Its next COLA anniversary,
policy month 24, falls at t = 10, and its frame has 682 rows, t = 0 … 681, to the
anchor’s last month, policy month 695. Point 22 is the anchor cell on the table basis
commencing 13 months after the valuation date: duration_mth(0) = −13, it is on the books
from t_entry() = 13, rows 0 to 12 are zeros, policy_year(0) is −1, and its frame has
709 rows.
Read on the policy clock |
Read on the valuation clock |
|---|---|
the payment months and the instalment schedule, the COLA anniversaries, the certain period and an installment refund’s derived period and final trim, the payments to date, the scenario’s months of death, the attained ages that key the mortality table and the improvement scale, the calendar year that dates the improvement, the commutation months, the utilization and the surrender charge by contract year, the age stop rule |
expense inflation, |
Expense inflation alone runs on t. SPIA_US_S’s annual steps, (1 + π)^(y(t) − 1), keep
their shape and move onto the valuation clock, so the maintenance charge is in
valuation-date dollars for every point alike and steps on each anniversary of the valuation
date. The commutation discount rate reads neither clock: it moves with the 10-year CMT’s
change since the annuity date, on one path of the CMT that every point shares. For a
contract on the books at the valuation date that is the change to the valuation date, an
opening-state column, plus cmt10_shift, a change made at the valuation date; a contract
commencing later, bought after it, has seen none (The opening state, below). A path of
the 10-year CMT would be read on the valuation clock, each contract taking the change on it
from the later of its annuity date and the valuation date. There is no acquisition cost in
either model: the premium is single and the cost is priced in.
Mortality improvement stays on the policy clock, because it is already dated by the
calendar. Its exponent is calendar_year(t) − mort_table_year, and
calendar_year(t) = annuity_year() + duration(t) is the calendar year the contract
reaches, whatever the valuation date. So a contract in payment reads the improvement of its
own calendar years, and nothing is re-based: restated from SPIA_US_S at month d, its
month t is SPIA_US_S’s month d + t and the same calendar year, and point 20’s
mort_rate(t, life) is SPIA_US_S’s point 9’s at 24 + t exactly. Moving it onto the
valuation clock would need a calendar valuation date, which the model point table does not
carry, and would step a generational basis on the valuation date’s anniversaries rather
than the contract’s.
That has a consequence for the shipped table. Every row keeps the annuity year of the
SPIA_US_S point it was taken from, 2026, so the rows are test cases standing at different
calendar dates at their common t = 0: the twins at their annuity date, point 16 fourteen
months later, point 22 thirteen months earlier. A real block carries each contract’s actual
annuity year, and its points then share one valuation date.
Because row t is the same month for every point, the frames of a block line up and sum
row by row, which is what run_sec.py --block prints:
import pandas as pd
frames = [model.Projection[i].result_cf()
for i in range(len(model.Data.model_point_table()))]
block = pd.concat(frames).groupby(level="t").sum()
On a point commencing at t = 0 the two clocks coincide, and the model computes what
SPIA_US_S computes, whatever the point’s count: neither model charges acquisition, and
every cash flow is the count times an amount per contract. On SPIA_US_S’s fifteen points
every cash flow and every count agrees, and so does every other cell the two models share
but three whose meaning changed: pols_if_init(), now the count already in payment at the
valuation date, 0 for such a point; model_point(), a row of another table; and
result_pols(), which gains pols_new_biz and sets pols_if first.
The in-force interface#
The model point table is model_point_table_sec.csv. It carries SPIA_US_S’s columns,
and six of its columns are the in-force interface: basiclife/BasicTerm_SE’s two, and
four that open a contract’s state. Every amount is per contract.
Column |
Unit |
Measured at |
Meaning |
|---|---|---|---|
|
contracts, not necessarily whole |
for a point in payment, the start of month 0, before any month-0 event; for any other, the month its annuity commences |
the contracts the point stands for: in payment at the valuation date, or commencing at or after it. A count of contracts on the books, never weighted by survival |
|
whole months |
the valuation date |
the months elapsed from the annuity date: positive in payment, 0 for an annuity commencing at the valuation date, |
|
a probability, 0 to 1 |
for a contract in payment, the valuation date, the start of month 0, before any month-0 death; for any other, the annuity date, where each covered life is 1 |
the primary annuitant’s survival: 1 or 0 on a real record |
|
a probability, 0 to 1 |
the same |
the joint annuitant’s survival; 0 on a single-life contract |
|
a fraction, 0 or more and below 1 |
the start of month 0, before any month-0 withdrawal |
the cumulative fraction of the certain instalments the owner has commuted before the valuation date, the notes’ |
|
a change in a rate, as a decimal: 0.005 for a rise of 50 basis points |
the valuation date |
the 10-year CMT at the valuation date less the 10-year CMT at the annuity date, which moves the commutation discount rate one for one; 0 for a contract commencing at or after the valuation date |
At the annuity date each covered life is 1, the fraction 0 and the CMT’s change 0, so a
point commencing at or after the valuation date carries those values, and the twins carry
SPIA_US_S’s own: 1 and 1 on a joint contract, 1 and 0 on a single-life one, no
commutation and no change. Where WholeLife_US_SEC’s opening state is 0 at issue, an
annuity’s survival opens at 1.
The count is a count of contracts, not of lives. A joint contract whose two annuitants have
died inside its certain period is one contract on the books, with both its lives at 0, and
is still paying. Survival is carried by the two life columns alone: the lives are
independent, as in SPIA_US_S, so their two probabilities are the whole survival state,
which a count weighted by survival could not carry. On a real record each life is 1 or 0,
and a joint contract may carry one life already dead; a death that has happened but has
not reached the record carries 1, and the model then projects that life as alive, as the
record does. Restated from SPIA_US_S at month d, each is SPIA_US_S’s probability,
lives_if(d, life). The commutation fraction is what the owner’s withdrawals have taken
from every certain instalment still to come: each withdrawal W at a commuted value CV
raises it from θ to θ + (1 − θ) W / CV, as in SPIA_US_S, and during the certain
period month 0’s instalment is the scheduled one times 1 − commute_frac_cum_init, so a
record of the instalment now paid gives the column as one less the ratio of the two. The
CMT’s change is a fact of the market, not of the contract’s history: the 10-year CMT on the
valuation date less the 10-year CMT on the contract’s annuity date, the same for every
contract bought on one date, from a published series.
|
|
Why |
|---|---|---|
|
|
The count, under BasicTerm_SE’s name. |
— |
|
The policy clock, in months. |
— |
|
|
— |
|
|
— |
|
|
Two things SPIA_US_S computes from the annuity date need no column. The payments to
date, which a cash refund nets and an installment refund counts against the premium, are a
deterministic schedule fixed at the annuity date, and the model sums them on the policy
clock (The opening state, below). The certain months left are
certain_mths_eff() − duration_mth, and none once duration_mth reaches the certain
period.
The columns carried over are read as SPIA_US_S reads them. For a contract in payment, the
facts they record are those of the annuity date:
Column |
Unit |
Measured at |
|---|---|---|
|
labels |
— |
|
dollars, the single premium |
the annuity date: a pricing input, which the projection reads only as the refund forms’ guarantee |
|
a rate |
the annuity date; reported in |
|
dollars a year, |
the annuity date: exogenous, and fixed then |
|
the payout form and the survivor terms, as in |
the annuity date |
|
a count of months from the annuity date, 0 for none |
the annuity date |
|
payments a year, 12, 4, 2 or 1; |
the annuity date; the payment months fall on the policy clock |
|
a rate a year, compound |
the annuity date; the income steps on each anniversary of it |
|
years, age nearest birthday |
the annuity date, not the valuation date: |
|
|
— |
|
flags; |
the annuity date |
|
a multiplier of mortality, the substandard rating, 1.0 as shipped |
the annuity date |
|
a calendar year |
the annuity date: the anchor of the generational improvement |
|
|
a modelling switch std, not a fact about the contract |
|
policy months, blank for a life that survives |
the scenario’s month of death, counted from the annuity date on the clock |
|
text: |
— |
A contract issued before its annuity date — the product allows up to twelve months’
deferral [S1] [S5] — is modelled as an annuity commencing later, a point whose
duration_mth is −k. SPIA_US_S collapses the annuity date onto the issue date, so the
short pre-income period between them, which carries a death benefit at one carrier only
[S2], is not modelled here either.
Three more columns, row_kind, source_policy_id and source_mth, record where the
generator took each shipped row from (below). No formula reads them, and an in-force
extract need not carry them: without them the model projects the same numbers, and
run_sec.py runs.
Data.model_point_table() checks the table as it reads it, over all rows at once. The
first check that fails raises ValueError, naming the missing column or every point that
fails it:
the six in-force columns are present;
no
point_idappears twice;policy_countis a number, zero or more, so not blank, text or infinite;duration_mthis a whole number of months, read by value, so that12.0is 12;duration_mthis −120 or more. Future new business is written over a horizon,Data.future_horizon_mth, 120 months as shipped, so that no frame runs longer than the stop rule from the annuity date plus ten years: 816 months on the anchor’s 65/62 pair, 1,080 for a single life at 40, the youngest age the shipped tables carry, and 1,560 at 0, the youngest issue age the model projects. Set to 0, the Reference refuses future new business altogether, and a negative horizon is itself refused;each life column is a probability, 0 to 1;
commute_frac_cum_initis a number, 0 or more and below 1;cmt10_shift_initis a number, of either sign;a single-life contract has no second life:
lives_if_init_2is 0;a contract not yet in payment,
duration_mth0 or less, holds its values at the annuity date: each covered life 1, no commutation and no change in the CMT;each month of death,
death_mth_1anddeath_mth_2, is blank or a whole number of months, read by value, so that13.0is 13 and a fraction or text is refused, on either basis; the table is returned with the two columns as the numbers they were checked as, which is what the projection reads;on the scenario basis each life’s opening status is its month of death’s: 1 while the life survives to the valuation date,
death_mthblank, negative orduration_mthor later, and 0 once it has died, so that the scenario’s step, which survival follows after the valuation date, agrees with the opening value at it;a commutation fraction appears only where a commutation could have been taken before the valuation date: the contract holds the right, its issue state allows it, it has a certain period, an elected one or an installment refund’s, and
duration_mthis 13 or more, the first withdrawal being taken in policy month 12 and reducing the instalments from month 13. That is a necessary condition only: the check cannot see an installment refund’s derived period, which needs the projection, nor whether enough of a certain period was left to commute, and it does not ask whether the model’s own utilization would have taken a withdrawal, since a real record’s withdrawals do not depend on it.
The surrender-charge scale, which SPIA_US_S reads from the same file, is checked too, by
Data.surr_charge_scale(): its policy years are read by value, once, so that 2.0 is year
2, and a year that is not a whole number, text and a blank among them, a gap, a repeat, a
year below 1 or a blank rate is refused, naming the file. surr_charge_rate(y) takes the
scale’s first and last years and its rates from there, where SPIA_US_S takes int() of
the raw years for its first and last, so that a year written x raises Python’s own
message and one written 3a turns the years to text.
A point at or past the stop rule, duration_mth ≥ stop_mth(), reads, but proj_len()
refuses it, naming the point. So does a contract that owes nothing after the valuation
date: in payment, its certain period over, and no life-contingent payment left, because
the form is certain_only or every covered life has died. Such a contract made its last
payment, or its refund, before the valuation date, and an in-force extract should not carry
it; it is Term_US_SEC’s point past its cover, for a product whose cover can end with a
death. The rule needs the certain period, which an installment refund derives from the
schedule, so it is the product’s rule and not the table’s, and each message says why
nothing is owed: a certain_only contract pays nothing after its certain period; every
covered life has died, and the certain period has ended; or every covered life has died,
on a form with no certain period. So a loop over the block meets such a row only when it
reaches it, after projecting the points before it. run_sec.py --block asks every point
for its frame before it projects any, and stops before it prints anything.
The model points#
No row of model_point_table_sec.csv is typed by hand. Every one is generated from
SPIA_US_S and its table by tests/sec_support.py, from the SPIA_US_SEC entry in its
SEC_SPECS, and the tests regenerate the table and compare, so an edit to a SPIA_US_S
row reaches it or fails the suite. In the source repository,
python tools/gen_sec_points.py SPIA_US_SEC writes it.
Point |
Kind |
From |
At the valuation date |
|---|---|---|---|
1–15 |
twin |
S points 1–15 |
commencing at |
16 |
derived |
S point 1 at S month 14 |
the anchor cell the month after its joint annuitant’s death: lives 1 and 0, paying 343.33 from |
17 |
derived |
S point 6 at S month 13 |
the cash refund in its annuitant’s month of death: the refund, 100,000 − |
18 |
derived |
S point 5 at S month 120 |
the 10-year certain period ending at the valuation date: the survivor reduction it deferred begins at |
19 |
derived |
S point 13 at S month 30 |
both lives dead inside the certain period: lives 0 and 0, the floor paying the full instalment, 530.45 rising to 652.39 at |
20 |
derived |
S point 9 at S month 24 |
the commuting point on the table basis, on its second anniversary: lives 0.986815 and 0.993436, and eligible to commute at |
21 |
derived |
S point 8 at S month 695 |
the anchor cell on the table basis in its last month, a one-row frame: the primary dead, aged past the limiting age, the joint annuitant alive with probability 3.84e-06 |
22 |
future |
S point 8, 13 months on |
commencing at |
A derived row’s opening state is what SPIA_US_S carries into its month d, each column
read as SPIA_US_S’s own formulas read it: each life’s survival to time d,
lives_if(d, life), before month d’s deaths; the commutation fraction applying in month
d, commute_frac_cum(d), before its withdrawal, which is 0 on every shipped row, because
commutation utilization ships at 0; and the CMT’s change since the annuity date,
SPIA_US_S’s cmt10_shift, which it applies from month 0 on, so that a row restated at d
has seen all of it, 0 on every shipped row, as cmt10_shift ships. Its policy_count is
SPIA_US_S’s
pols_if_init(), the contracts the point stands for, and not SPIA_US_S’s pols_if(d),
which is the closing obligation measure: the survival is in the life columns. So the row
continues the S projection from there. Its policy_id is the S row’s with the month
appended, IA-000001-M14, and a future row’s carries the months to the annuity date,
IA-000008-F13. Row t of a generated point is month t + source_mth of its S point.
All 22 are at issue ages 65 and, where joint, 62, as SPIA_US_S’s points are. The shipped
mortality table and improvement scale carry ages 40 to 120, so a point on the table basis
at a younger issue age needs both extended first.
Counts and timings#
pols_if_init() is the count in payment at the valuation date: policy_count for a point
already in payment, 0 for any other. pols_new_biz(t) is policy_count in the month the
annuity commences, the month with duration_mth(t) = 0, and 0 in every other: new business
in basiclife/BasicTerm_SE’s sense, a contract entering the books, with no premium,
because the single premium is a pricing input, as in SPIA_US_S. pols_if_at(t, timing)
has two timings, basiclife/BasicTerm_SE’s:
BEF_NB, the contracts carried in from montht − 1, before montht’s annuities commence:pols_if_init()att_entry(), the first month on the books, and the wholepolicy_countafter it, to the stop rule;BEF_DECR, that count pluspols_new_biz(t), which weights every cash flow of montht.
Any other timing raises. The count is not decremented. SPIA_US_S weights every flow
by its constant pols_if_init() and carries mortality in each life’s lives_if, and this
model does the same on the count on the books: every cash flow is
pols_if_at(t, BEF_DECR) times an amount per contract weighted by survival. So
BEF_NB is a closed form, the same float that a recursion
BEF_NB(t − 1) + pols_new_biz(t − 1), as Term_US_SEC’s, would give, with no chain of
calls behind it. The count leaves the books only at the stop rule:
pols_if_at(t, BEF_DECR) − pols_if_at(t + 1, BEF_NB) is 0 at every t of every
frame but the last, where it is the whole count, at the end of the last projected month.
SPIA_US_S has no maturity, and neither has this model.
pols_if(t) keeps SPIA_US_S’s definition, the notes’ obligation measure IF(t), on the
count on the books: pols_if_at(t, BEF_DECR) × max(C(t), l_alive(t + 1)), the contracts
with a payment obligation still open at the end of month t, with the life-contingent leg
dropped on certain_only, as in SPIA_US_S. It carries the maintenance expense. It is a
closing measure, not the count before decrements: on point 8, the anchor cell on the table
basis, pols_if(0) is 0.99999986 against a count of 1, as in SPIA_US_S; on point 17, the
cash refund in its month of death, it is 0; and on point 21, the anchor cell in its last
month, 3.41e-06, SPIA_US_S’s pols_if(695). So the registry marks the model
closing_pols_if, and the convention every other _SEC model meets,
pols_if(t) = pols_if_at(t, BEF_DECR), skips it. The count on the books is not a column
of result_pols(): it is the table’s policy_count, from the annuity date to the stop
rule.
pols_new_biz, and no lapse. SPIA_US_S’s tests forbid pols_new_biz on a SPIA,
beside pols_lapse, lapse_rate, surr_value, cash_value and av_pp: the contract has
no account value and no surrender right, so there is no lapse decrement, a position VM-22
makes prescriptively for this reserving category R2 REG-R36. Here pols_new_biz
exists, because an annuity commencing after the valuation date is a contract entering the
books, and it means only that. The model has none of the other five.
Cover is is_active(t), 0 ≤ duration_mth(t) < stop_mth(), and outside it, before the
annuity commences and from the stop rule on, every count is zero, and so every cash flow.
No count evaluates a rate there, and no cell reads a policy year or an attained age the
contract does not have: is_payment_mth and commute_elig are false, and the scheduled
and payable instalments, the certain floor, the payment factors, the mortality and
improvement rates, the commuted value, the commutation fraction, the refund, the
withdrawal and its surrender charge are zero before any table or schedule is read.
lives_if and lives_if_last are zero before the contract is on the books.
Three chains of calls run from month t back to t_entry(), each one cell a month, as in
SPIA_US_S: survival on the table basis, lives_if; the commutation fraction on every
point, commute_frac_cum, which recurses whether or not the contract can commute; and the
payments to date on a refund form, cum_annuity_pp, back to the valuation date’s policy
month. The longest sets how deep a cold call runs, counted as modelx’s stack trace counts
it; mx.set_recursion admits a call one level deeper than the limit it is given. A cold
net_cf in the last month of the anchor’s 696-month frame on the table basis, point 8, runs
709 cells deep, 696 of them lives_if, a recursion limit of 708, against 705 cells in
SPIA_US_S and 706 before compiling, which added the reads of the tables’ arrays at the
chain’s foot; on the scenario basis, point 1, it runs 703 deep, 695
of them commute_frac_cum; on the cash refund in payment 13 months, point 17, 654 deep, 647
of them cum_annuity_pp; and on point 22, commencing 13 months on, 709 again, because its
chains stop at t_entry(). At the longest cover the contract allows, 1,440 months from
issue age 0, the youngest the model projects on any form, in a copy whose mortality table
and improvement scale are extended to age 0: a single-life cash refund on the table basis
runs 1,453 cells deep, a recursion limit of 1,452, at the valuation date and commencing 120
months on alike, and so does a joint life annuity certain issued at 0 and 0 with a certain
period of 1,440 months, the longest proj_len() admits, commencing 120 months on: the
deepest call the contract allows; a certain_only annuity issued at 0 runs 1,452 deep.
Each report evaluates its columns in ascending t, and a sweep of the committed points
that way, every report and check, runs 12 cells deep, a recursion limit of 11.
The opening state#
SPIA_US_S projects every contract from its annuity date, with each covered life alive,
no commutation taken and the CMT where it stood at purchase. A contract valued in payment
needs what those have become by the valuation date. Read cell by cell, SPIA_US_S’s
recursions carry two quantities along a path, survival per life and the commutation
fraction, which are three state columns, and two that follow from the contract’s terms
alone, the payments to date and the income by policy year, which need none. One input is a
point-to-point quantity on a market path whose term began before t = 0, the CMT’s change
since the annuity date, and its value at the valuation date is the fourth column.
Survival per life. Each life column opens lives_if at t_entry(); from there the
table basis decrements it month by month, and the scenario basis follows the months of
death on the policy clock, lives_if(t, life) = 1{duration_mth(t) ≤ death_mth(life)},
which Data holds the opening status to. The derived rows show each case:
Point 16, the anchor cell in payment 14 months, opens with lives 1 and 0, its joint annuitant having died in policy month 13. On the either trigger it pays two thirds of the instalment from
t = 0, 343.33,SPIA_US_S’s month-14 figure, and the COLA continues on the unreduced income, to 353.63 fromt = 10.Point 19, the certain-floor case, opens with both lives at 0 inside its 10-year certain period. The life-contingent factor is 0 and the floor 1, so it pays the full instalment, 530.45 at
t = 0rising with the COLA to 652.39 att = 89, policy month 119, withpols_ifat 1, and nothing fromt = 90, wherepols_ifand the expense fall to 0 together.Point 20 opens with two fractional lives, 0.986815 and 0.993436,
SPIA_US_S’s survival of the anchor pair to month 24 on the table basis.Point 21 opens with the primary at 0, dead with certainty once past the limiting age, and the joint annuitant at 3.84e-06, in the last month of the frame.
The commutation fraction. commute_frac_cum_init is path-dependent, because it
records the withdrawals actually taken, so the contract’s terms cannot re-derive it.
Commutation utilization ships at 0, so no shipped row has commuted, and the column is 0 on
all 22. Switch it on as the splice does, before either model computes anything:
commute_util_base = 0.5 in both, and the CMT 50 basis points up since the annuity date,
SPIA_US_S’s cmt10_shift at 0.005, which a row restated in payment carries as
cmt10_shift_init, this model’s cmt10_shift then being 0. SPIA_US_S’s point 9
withdraws 25,485.58, half its commuted value, at policy month 12, the first month a
withdrawal is allowed, and its certain instalments are halved from month 13. Restated in
payment 13 months, it opens with commute_frac_cum_init 0.5. It pays 257.50 at t = 0,
half the 515.00 scheduled, withdraws 11,735.74 at policy month 24 and receives 17,115.93 in
instalments over the rest of its certain period, each SPIA_US_S’s figure. With the column
at 0 it would pay 515.00 at t = 0, withdraw 23,471.48 at policy month 24 and 10,635.96
more at month 36, and receive 21,808.98: the figures of a contract that never commuted.
From policy month 120 both pay the life-contingent instalment in full, and alike, because
a commutation reduces certain instalments only.
The CMT’s change since the annuity date. The commutation discount rate is
j = j0 + [CMT10(t) − CMT10(0)], 0 the annuity date: the base rate, 4.00% std,
moved one for one with the 10-year CMT’s change since purchase. SPIA_US_S reads the change
from one Reference, cmt10_shift, and every one of its points commences at its own t = 0,
so one value fits them all. Contracts in payment at a valuation date were bought at
different dates and have seen different changes, which no one value holds. So every contract
of a block reads the change on one path of the CMT, which every point shares, as it shares
every economic input, each from its own annuity date. A contract on the books at the
valuation date, in payment or commencing then, has seen cmt10_shift_init by that date, and
sees cmt10_shift, the change made at the valuation date, from month 0 on, as SPIA_US_S’s
contract sees its cmt10_shift from its annuity date: its rate is
j0 + cmt10_shift_init() + cmt10_shift, added in that order. A contract commencing later is
bought after that change and has seen none of it, so its rate is j0. The column ships at 0
on every row, as cmt10_shift does. Set to 0.005 on point 20, the commuting point in
payment 24 months, the CMT 50 basis points up since its annuity date, point 20 discounts at
4.5%, its commuted value at t = 0 46,942.96, SPIA_US_S’s point 9 at its month 24 with
its cmt10_shift at 0.005, while in the same read its twin, point 9, commencing at the
valuation date, discounts at 4.0%, its commuted value at policy month 12 52,062.79,
SPIA_US_S’s on the shipped 0, and so does the same contract commencing 13 months later, a
row the tests add, at its policy month 12. With cmt10_shift at 0.005 too, the CMT up 50
basis points more at the valuation date, point 20 discounts at 5.0% and point 9 at 4.5%,
while the contract commencing 13 months later, bought after the rise, still discounts at
4.0%, its commuted value unmoved. The rate is level: it reads neither clock. A path of the
10-year CMT would be another input table, read on the valuation clock, each contract taking
the change on it from the later of its annuity date and the valuation date.
The certain months left need no column. certain_floor(t) is
1{duration_mth(t) < n_eff} on the policy clock, and the effective certain period n_eff
is fixed at the annuity date: the elected one, or an installment refund’s, which
certain_mths_refund() derives from the schedule. Point 18 is valued at policy month 120,
where its certain period ends, so the survivor reduction it deferred begins at t = 0:
447.97, two thirds of the 671.96 the COLA has reached, where SPIA_US_S’s point 5 paid the
full instalment through month 119.
The payments to date need no column either. cum_annuity_pp(k), the notes’ G(k), is
the instalments scheduled before time k: a deterministic as-if-alive schedule, fixed by
B(1), the COLA, the frequency and the timing, which a cash refund nets on death and an
installment refund searches for the premium. It stays on the policy clock, keyed as
SPIA_US_S keys it, and only its recursion’s base moves: at the valuation date’s policy
month, duration_mth(t_entry()), one loop sums the instalments scheduled before it, the
same additions in the same order as the recursion, so G is SPIA_US_S’s to the last bit,
and a later key recurses back to that one, a month at a time. Point 17, the cash refund in
payment 13 months, reads G(13) = 12 × 500.00 + 515.00 = 6,515.00 and pays the refund of
93,485.00 at t = 0, as SPIA_US_S’s point 6 pays at its month 13; its result_cf() on a
fresh read evaluates G at keys 13 to 659 alone. Recursing from the annuity date, as
SPIA_US_S’s does, the first refund of a contract long in payment would recurse as deep as
the contract is old: a cash refund in payment 600 months reads G(600), which in
SPIA_US_S runs 606 cells deep from cold, a recursion limit of 605, where this model’s
whole result_cf() for it runs 9 deep, a limit of 8. The income by policy year,
annual_income(y), is based the same way, at the valuation date’s policy year, where in
SPIA_US_S the anchor cell’s annual_income(58) recurses through 58 annual_income
cells, back to B(1).
Departures from SPIA_US_S#
Each formula that tested t against a contractual event now tests the policy clock, each
read of the schedule at a month is a read by policy month, and every recursion on the
valuation clock begins at t_entry(). Of SPIA_US_S’s 72 Projection cells, 22 are
unchanged, 14 have a new docstring only and 36 are rewritten, and 23 cells are new, 95 in
all. Of its five Data cells, three are unchanged, one has a new docstring and one, the
model point table’s reader, is rewritten, and one is new, surr_charge_scale. None is
removed or renamed, which the twin identity asserts: a cell of SPIA_US_S’s that this
model lacked would fail it. Compiling then changed how each cell reads its inputs and
spells its codes, and no number: it added three cells to Projection, point_id,
mort_schedule and improvement_schedule, 98 in all, and 64 to Data, 70 in all (The
compiled model, below); of SPIA_US_S’s cells it changed the signature of one, claims,
now of t alone, which the twin identity compares with SPIA_US_S’s claims(t, None)
and claims(t, "REFUND"). Projection’s point_id Reference gave way to idx;
commute_disc_convention, which held text, holds an int code; and the codes,
issue_age_min are new References, as is Data’s np.
Cells |
|
|
Why |
|---|---|---|---|
|
|
|
The policy clock, opened from the model point |
|
|
|
The frame starts at the valuation date. |
|
the column’s 1.0, the weight of every flow |
|
Contracts in payment open the count; an annuity commencing joins it as new business in its month |
|
|
|
The count on the books weights every flow |
|
indexed by |
indexed by |
Survival is carried forward from the valuation date, from the contract’s state there |
|
0 at |
|
A contract in payment may have commuted already |
|
recursions from the annuity date, |
still on the policy clock, |
A contract valued late in life reads its payments to date and its income without recursing back to the annuity date, to the last bit the same |
|
|
the same tests on |
On the valuation clock month |
|
the remaining certain instalments over months |
the same over policy months, read from |
The same reason, and no closure in a cell the commutation fraction’s recursion runs through |
|
|
on a contract on the books at the valuation date, |
Contracts in payment bought at different dates have seen different changes, which one Reference cannot hold; on the one path a block shares, a contract bought after the valuation date has seen none of a change made at it |
|
the scale’s first and last years by |
the years, the first and last among them, and the rates from |
A year written as text raised Python’s own message or turned every lookup into a miss |
|
branch on the text of |
branch on eight flags, |
No projection formula compares text or calls a label accessor, which are left to reporting, so that the compiled form can type every cell |
|
the table joined on age and sex in the monthly cell |
the limiting-age test kept there, the table read through |
One reader per table, keyed by attained age, called only at ages the table holds |
|
unguarded: no |
zero or false outside the frame, |
A month before the annuity date has |
|
|
|
Unit costs in valuation-date dollars, stepping on the valuation date’s anniversaries |
|
|
|
The counts first, after |
The other new cells are policy_count, duration_mth_init, lives_if_init,
commute_frac_cum_init, cmt10_shift_init, t_entry, is_active, pols_if_at and
pols_new_biz. One
difference shows on invalid input alone: an invalid commute_disc_convention raises
wherever a certain month remains to discount, where SPIA_US_S raises at the first
instalment it discounts.
Of the cash flows, the change of clock moves the maintenance expense alone, and
liability_cf and net_cf with it. A contract in payment carries that expense in
valuation-date dollars. Point 18, valued on an anniversary, has expenses(t) equal to
SPIA_US_S’s expenses(120 + t) divided by 1.025^10, about 1.280, at every t; off an
anniversary the steps fall on the valuation date’s anniversaries rather than the
contract’s, so point 16’s are SPIA_US_S’s from month 14 on divided by 1.025 in some
months and by 1.025² in others. Their other cash flows and their counts are SPIA_US_S’s
from their months on. Point 22 is SPIA_US_S’s point 8 thirteen months on in those columns
too, and its maintenance expense is SPIA_US_S’s times 1.025 or 1.025².
The compiled model#
The model compiles under modelx-cython into C-typed code, as basiclife/BasicTerm_SC does,
and modelx reads and runs the same formulas as before. Compiling changed how each cell
reads its inputs and spells its codes, and no number: what the model computed on each
committed point was frozen before the change, and it still computes it (Tests, below).
Cell by cell, at every argument a full modelx sweep evaluates, the compiled model computes
what modelx computes, bit for bit, on the committed points, on the points of the splice
grid, which take the branches they do not, on the contract’s longest frames, where a
commutation’s floors bind, on keys written as floats and on a sex that is not text, and
where the cap on mortality binds or a NaN reaches it. The compile tests hold it so on
x86-64, and to 1e-12 relative elsewhere, where no run has shown it yet.
Building it#
In the source repository:
python tools/build_sec_cy.py immediate_annuity # in place, beside the model
python tools/build_sec_cy.py immediate_annuity --out /tmp/spia # elsewhere, with the CSVs
The tool exports the model to SPIA_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 SPIA_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/immediate_annuity") # the directory holding the build
from SPIA_US_SEC_nomx_cy import mx_model as model
model.Projection[15].result_cf() # point 16, 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 = 15 after Projection.result_cf() leaves point 1’s
frame cached, while point_id(), not yet computed, reads point 16’s label, and
Projection.expense_maint set to 90 once Projection[0] has computed point 1’s
expenses(0) leaves it at 5.0, where an ItemSpace made after, Projection[1], computes 7.5
for point 2’s. Set every Reference on a model just imported, before anything is computed,
where modelx would recompute; a test holds the compiled model to this.
A build takes 35 to 40 s here, with MSVC, 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.cp313-win_amd64.pyd 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
87 of its 95 Projection cells as C numbers. Three took a timing or a kind as text,
pols_if_at, claim_pp and claims, whose kind could be None, and those three and
sex, a label, kept a dictionary for a cache; the bodies of the typed cells still called
pandas and Python: a model_point() lookup for each attribute a formula reads, text
compared in each of the eight decodes, pd.isna on each month of death, a .loc on a table
for each attained age’s mortality and improvement and each contract year’s surrender charge,
a list built and its min taken for the age stop. It ran 2.0 times its own export, 7.57 ms
a point on net_cf against 14.9, over the committed points, measured once, on a build of
the stage-E model with a sample and a spec of its own, which are not shipped. 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[15]is point 16, andpoint_id()returns the label, which every refusal names. The position is what indexes the vectors below.Data’s vectors. Each model point column a formula uses is aDatavector of int64 or float64, one element a point, named as the column, and a cell reads its point’s element asSPIA_US_Sreads the point’s value:premium_pp()isfloat(data.premium()[idx]), an age isint()of its element and a flagbool()of its. Compiled, the vector is a typed memoryview, and the read is a load from memory. Where a point’s value can be one its projection cannot use, a 0/1 vector beside it,premium_ok()and the like, says whether it is usable, and the accessor refuses the point where it reads the element (What it refuses, below).Text, decoded once. A C cell holds no text, so
Datadecodes each text column a formula branches on into 0/1 flags, for every point at once: the form intois_period_certain,is_certain_only,is_cash_refundandis_installment_refund, the trigger intois_trigger_either, the timing intois_arrearsand the basis intois_scenario; and beside each column ahas_*flag, whether the value is oneSPIA_US_Snames. Each decodes asSPIA_US_Scompares the column, exactly, case and whitespace included, so a value no flag names sets nohas_*flag, and the decode that reads it raisesSPIA_US_S’s message,invalid formand the like, where the projection first meets it, as at stageE. A flag column,joint,commutation_enabled,issue_state_excludes_withdrawalorqualified, isbool()of each element as pandas reads it, asSPIA_US_S’sbool(model_point()[...])is. A blank month of death, whichSPIA_US_Sreads as a survivor throughpd.isna, is -1 indeath_mth_1anddeath_mth_2.Tables indexed by integers. The mortality table and the improvement scale, keyed by age and sex, are each numbered by its own sexes, in sorted order, from 1, and held by schedule and attained age in
mort_table_arrayandimprovement_array, padded with NaN from age 0 so that the age is the index, with the first and last age of each schedule beside them. Each point carries the schedule of each life’s sex in each table, read throughmort_schedule(life)andimprovement_schedule(life), and each table’s one reader,mort_rate_base_at(x, life)orimprovement_rate_at(x, life), checks the age against the schedule’s extents before it reads, so nothing reads the padding. A sex a table lacks, a blank among them, is schedule 0 there, a row of padding whose first age is 1 and whose last is 0, which the reader refuses at the first age it reads, naming the point, the age and the life, whereSPIA_US_S’s.locraisedKeyError: no point on the scenario basis reads it, nor any single-life point’s second life, so neither is refused. The two tables are numbered apart, so a sex one holds and the other lacks shifts neither numbering. The surrender charges are a vector by contract year, padded from year 0, with the scale’s first and last years beside it, andsurr_charge_rate(y)reads it atyclamped to them, asSPIA_US_Sreads the scale’s first and last rows beyond them.Codes. A timing, the kind or the commutation discount convention, which
SPIA_US_Sspells as text, is an int Reference named as the text: the count’s timingsBEF_NB = 0andBEF_DECR = 1, the kindREFUND = 0, and the conventionsCOMPOUND = 0andSIMPLE = 1, whichcommute_disc_conventionnow holds,COMPOUNDas shipped. A call reads as before, less the quotes:pols_if_at(t, BEF_DECR),claim_pp(t, REFUND). A string argument would give the cell a dictionary for a cache, where a code indexes a C array, so codes are numbered from 0 without a gap, the timings by instant, as in every SEC model. A cell compares a code with==or!=alone, so that a text passed where a code is taken meets the cell’s own refusal in modelx too:invalid timing,invalid kindorinvalid commute_disc_convention. TheProjectiondocstring’s Codes lists the five.One kind, no total.
SPIA_US_S’sclaims(t, kind=None)is one kind’s claims or, withNone, their total, and the cash refund is its only kind, so the total is that kind’s claims and no sum. Hereclaims(t)takestalone and is that kind’s formula, the same product in the same order, with no0.0 +that would turn a-0.0into0.0;claim_pp(t, kind)keeps its kind, as the code. The twin identity comparesSPIA_US_S’sclaims(t, None)andclaims(t, "REFUND")withclaims(t)(Tests, below).No list.
horizon_mths()finds the younger of the two issue ages by one comparison, whereSPIA_US_Stakes theminof a list; the commuted value and the withdrawal were loops over policy months already, since running in force. And the payments to date and the income by policy year are based at the policy month and year of the valuation date read from the model point,max(duration_mth_init(), 0)and that// 12 + 1, where at stageEthey read them through the clock att_entry(): the same keys, so no number moved.No Python call kept. No formula outside the reporting cells calls a Python builtin outside its refusals but
int,float,bool,min,maxandrange, which Cython turns into C, sotests/us_registry.pyadmits none.payment_freq()compares the element with each of 12, 4, 2 and 1 rather than holdint()of it in a local, which would keep a Python object in the cell. No cell is uncached, and none takes a float.Reporting cells stay Python.
model_point(), the label accessorsform(),reduction_trigger(),payment_timing(),mort_basis()andsex(life), and the two reports return a table row, text and DataFrames, for a reader, forrun_sec.pyand for the comparison withSPIA_US_S. No other cell calls them, so they cost the projection nothing. Each label returns its point’s column:form,reduction_triggerandmort_basisthe column of their own name,payment_timingthetimingcolumn andsex(life)theprimary_sexorjoint_sexcolumn by life, which the registry entry declares in"reporting_columns", so that the conventions hold each label to the column it returns. The first four validate their column, asSPIA_US_S’s do, so each returns text or raises, and compiles to a Pythonstr.sex(life)returns its column as read, andDataaccepts a sex that is not text: a single-life point’s blank second life, which reads as NaN, or a number, whichSPIA_US_Sprojects on the scenario basis, which never joins a table. So it compiles to a Python object, as the sample traces it (below), with the one dictionary for a cache inProjection, and returns what modelx returns. The two checks are reporting cells too, but they return a verdict, which compiles to a Cbint.
The Data docstring lists its vectors, arrays and counts, each with the column or file it
comes from: 42 vectors of int64 by point and 11 of float64, the 14 _ok flags, the four
flag columns and the 11 flags decoded from text among the first; the mortality table and the
improvement scale, float64 by schedule and attained age, and their first and last ages,
int64 by schedule; the surrender charges, float64 by contract year; and four int counts and
extents, each a table’s check, mort_sexes and improvement_sexes among them. The six
readers stay Python, returning DataFrames and a path, and no Projection cell but
model_point() reads them. Every other cell of Projection, 90 of its 98, 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,562 by |
the 32 cells of |
a C array of 1,562 by 3 |
the nine cells of |
a C array of 1,442 by |
|
a C array of 122 by |
|
a C array of 121 by 3 |
|
a C array of 3 |
|
one |
the 36 cells without a parameter: the point’s label, numbers, decodes and flags, its opening state, its certain periods, the ends of its frame, the discount convention decoded, and the two checks |
a Python object |
the eight reporting cells but the checks |
The declarations the build generates, _mx_classes.pxd in the compiled package, are the
record of it, and the one dictionary among Projection’s caches there is sex’s.
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 two reports
and the two checks on every committed point, which reach every cell but these:
model_point() and the five label accessors, which only a reader asks for; point_id(),
which only a refusal names; premium_tax_rate(), premium_net_pp() and qualified(),
which the model reports and no flow reads; lives_death, each life’s death density, which
the last-death density replaces in every flow; and surr_charge, the charge the insurer
keeps, which no column shows. The sample calls those too, the monthly ones in every month
of the frame and the month after it, lives_death for both lives. Every timing of
pols_if_at and the one kind of claim_pp are reached by the reports. 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. It calls sex(1) and sex(2) once more, on a copy of the table’s first point
with both sexes 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
sex as a Python object, so that a blank or numeric sex returns what modelx returns
rather than raising TypeError (What compiling changed, and why); the other four labels
validate their column, and a blank would make them raise, so the run calls them on the
committed points alone. The committed points leave branches untaken: quarterly,
semi-annual and annual payments in arrears, a withdrawal taken, the residual floor
binding, the simple discount, a rating that caps mortality, the age stop inside a certain
period, the installment refund’s trim below monthly, a COLA on a refund form. That still
types every cell, because every branch of a cell returns the one type its others return,
a rate a float in every branch, and on points that take those branches the compiled model
computes modelx’s numbers (Tests, below). 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 lives_if reads 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,562 |
1,560. The longest frame is any form on a youngest life of issue age 0, the youngest |
|
1,562 by 3 |
the lives 1 and 2, the timings |
|
1,442 |
1,440, 12 × ( |
|
122 |
120, the policy year of policy month 1,439, read by the income by policy year at the schedule’s months, by the utilization inside a certain period, and by the surrender charge in every month of the frame |
|
121 by 3 |
119, the last attained age below |
|
3 |
2, in |
proj_len() refuses, naming the point, a covered life whose issue age is below
issue_age_min, 0, on every form, the primary’s and the joint annuitant’s each asked, a
departure: SPIA_US_S projects an annuity whose primary or joint issue age is below 0,
which SPIA_US_SEC refuses, a negative age being outside every contract, as Term_US_SEC
refuses its contract’s bounds in proj_len(); and an elected certain period above 12 * (omega_age - issue_age_min), 1,440 months, the longest the caches hold. It asks before it
asks the stop rule, since the installment refund’s period, which the stop rule reads,
searches the payments to date up to the age stop, past the k cache on a point issued
younger. SPIA_US_S projects every form at any issue age, its frame running to the age stop
on its youngest life, so the caches are sized for issue age 0 on every form, below the 18
product-spec.md issues a lifetime form at: refusing a lifetime form below 18 would refuse
a point SPIA_US_S projects, which stage E projected (D2). A Projection ItemSpace is
about 16% larger for it (What a compiled run needs, below). issue_age_min, omega_age
and Data.future_horizon_mth are the contract the sizes are derived from. Raise omega_age
or the horizon, and a report runs past the caches in the compiled model alone: a frame of
more than 1,561 months, a policy month past 1,441, a policy year past 121 or an age past 120
raises IndexError, naming nothing, where modelx projects. Each needs the sizes derived
again, as spec_sec.py derives them, and a rebuild: t raised to 12 × (omega_age −
issue_age_min) + the horizon + 2, k to 12 × (omega_age − issue_age_min) + 2, y to
omega_age − issue_age_min + 2, and x to omega_age + 1. The shipped tables start at
age 40, so a point on the table basis at a younger issue age is refused today by its first
rate, naming it; the ages from 0 are the contract’s, which extended tables reach.
Two compiler directives#
tools/build_sec_cy.py marks the module mx2cy translates # cython: infer_types=True, cpow=True, and compiles it with -ffp-contract=off on every platform but Windows, as
Term_US_SEC’s Two compiler directives sets out, with what each costs and what it was
measured to change there. Here cpow reaches four powers: the monthly mortality rate,
1 − (1 − q)^(1/12) in mort_rate_mth, the generational improvement,
(1 − G2_x)^k in mort_rate, the compound commutation discount, (1 + j)^(−(s − m)/12)
in commuted_value, and expense inflation, (1 + π)^(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 Windows MSVC compiles without
the flag, since it emits no fused multiply-add for x64 without /arch:AVX2, which
setuptools does not pass, and the comparison is exact there too. On the same platforms as
the flag 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). MSVC accepts two widths without a
word, so on Windows the one width rests on a test that holds every 2-D size in
spec_sec.py to the one width (Tests, below).
What a compiled run needs#
Memory, and the release. A compiled Projection ItemSpace is a C struct of 1,147,464
bytes, about 1.1 MB, the type’s basic size, which holds every cell’s cache, each beside a
flag array of its shape that marks what is computed. Its 41 caches of 1,562 months, 32 by
t alone and nine 3 wide, are most of it. That is 2.7 times Term_US_SEC’s and about
WholeLife_US_SEC’s, for frames of 1,562 months, which any form at issue age 0 sizes: it is
about 16% larger than it would be sized from 18, the youngest age product-spec.md issues a
lifetime form at. Making one costs time as well as memory: Python zeroes the struct when it
makes the ItemSpace, and making and releasing one, nothing computed, the runner’s collection
included, took 0.26 ms here, of the 0.81 ms a compiled point takes (Speed, below).
Deleting it, del model.Projection[idx], frees nothing by itself: an ItemSpace sits in
reference cycles, and only Python’s cyclic collector frees it. That is why run_sec.py --block collects after each release, in its frame pass and in its projections (Run it,
above), and a compile test holds a compiled block run to one point’s ItemSpace at a time.
Without it, 506 compiled points peaked at 540 MB (Speed, below).
Stack, not recursion limit. A compiled chain of cells calls C to C, on the C stack,
which the interpreter’s recursion limit does not count, so the compiled model needs no limit
raised. What it needs is stack. The deepest call the contract allows, a cold net_cf in the
last month of the longest cover, 1,440 months, runs a chain of one cell a month back to
t_entry(), from issue age 0: 1,453 cells deep in modelx on a cash refund, commencing now
or 120 months on, and on a joint life annuity certain issued at 0 and 0 with 1,440 certain
months, commencing 120 months on, and 1,452 on a certain_only annuity. Compiled with MSVC
14.37, on this machine, each runs on a thread of 384 KiB of stack and dies on one of 320, as
does every other longest cover. Windows rounds a thread’s reservation up to 64 KiB, so the
bytes a level were read from the longest chain that runs at fixed reservations, in steps of
40 months: 360 months at 128 KiB, 640 at 192 and 920 at 256, 280 months more for each 64
KiB, 234 bytes a level, and 37 to 46 KiB besides, so about 377 KiB at 1,453 levels; at 320
KiB, 1,200 months ran on one run and died on a second. A test runs the call 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, and which reserved
2,031,616 bytes here: 2.7 and 5.2 times the need. gcc’s frames are another compiler’s, and
the cython CI job, which runs the test on Linux too, is the check on them: the test first
runs the call at nine stacks, from 256 KiB to 2 MiB, and reports the smallest it ran on. At
the 232 to 288 bytes a level gcc took on the chains of the models compiled before this one,
the chain alone at 1,453 levels needs about 330 to 410 KiB. A stack below the need kills its
child on an overflow, by design; 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,931 there, 2,929 on the certain_only annuity, and the two reports and
the two checks, which run in ascending t, need 154 with the package’s import among the
frames they run under. So sample_sec.py sets 12,000, four times the first rounded up to
the thousand, and a test holds it to that derivation.
What it refuses#
The compiled model refuses what modelx refuses, with the same message. modelx raises its
FormulaError, which quotes the error; compiled, the error itself propagates.
What
Datacannot read for the whole table, when the array is first read, naming the table and its points or lines: whatmodel_point_table()refuses, as at stageE(The in-force interface, above); a label that is not a whole number below2**53in size,model_point_table_sec.csv: point_id must be a whole number; [3.5] is not, fromData.point_id, when a label is first read; and inmort_table.csvorimprovement_scale.csvan age that is not a whole number,mort_table.csv: age must be a whole number; it is not on line [2], a blank sex, a rate that is not a finite number, or a sex whose ages do not run from its first to its last, or run below 0,mort_table.csv: the ages of sex F must run from -1 to 120 without a gap or a repeat, none negative, by the table’s check, which every array, extent and schedule of the table reads first.SPIA_US_SraisedKeyErroronly where a projection read a missing key, and read a blank rate as NaN. A key written as a float, an age40.0, is read by its value, asSPIA_US_S’s lookups match it.What a point’s projection cannot use, by the cell that reads it, naming the point, and no other point for it: a value that is not a number,
point_id 1: premium_tax_rate must be a number or blank; it is not; an age, a month count, a frequency or a year thatint()cannot read, or of2**53or more in size, which an int64 cannot be trusted to hold,point_id 3: primary_age must be a number int() reads, below 2**53 in size; it is not; and a blank or infinite amount or rate on a point whose projection reads it through amax, aminor a search that would turn the missing value into a number: the premium on a cash or installment refund,point_id 6: premium must be a number, and a finite one on a cash or installment refund, which reads it; it is not, the first year’s income and the COLA rate on every point, the survivor percentage on a joint contract with a life contingency and the rating on the table basis. That isTerm_US_SEC’s rule for a value a cap, aminor amaxreads (its What it refuses), applied by point where Term applies it over the whole table, so that the model refuses no pointSPIA_US_Sprojects to a number, as at stageE. A blank premium on a life annuity is NaN, as inSPIA_US_S, and a single-life point’s blankjoint_age, a blankcertain_monthson a form without an elected period and a blankannuity_yearon the scenario basis are read by no projection, and refused only by a direct call of the accessor. A fraction in an int column truncates, asSPIA_US_S’sint()does, so a frequency written12.5is monthly.A value of
form,reduction_trigger,timingormort_basisnone ofSPIA_US_S’s values names, compared exactly, case and whitespace included, by the decode that reads it, withSPIA_US_S’s message,invalid form, as at stageE; and a frequency other than 12, 4, 2 or 1,invalid frequency.An attained age a table lacks, by its reader, naming the point, the age and the life, where
SPIA_US_S’s.locraisedKeyError:point_id 8: mort_table.csv has no mort_rate at attained age 65 for the sex of life 1on a point on the table basis whose sex the table lacks, which is schedule 0, and the same at 17 on acertain_onlyannuity issued at 17 on the shipped tables, which start at 40.By
proj_len(), before the stop rule, a contract the caches do not hold and no contract is, each covered life’s issue age asked, in this order: a covered life issued belowissue_age_minon any form,point_id 8: issue age -1 is below issue_age_min, 0, and an elected certain period above 1,440 months,point_id 5: certain_months 1441 is above 12 * (omega_age - issue_age_min), 1440, the longest certain period the caches are sized for; then, as at stageE, a point at or past the stop rule and a contract owing nothing.A timing, a kind or a life a cell does not take,
ValueError("invalid timing"),ValueError("invalid kind")andValueError("invalid life"), where it is inside the cell’s cache:pols_if_at(0, 2),claim_pp(0, 1)andclaim_pp(0, 2), and a life of 0,lives_if_init(0),death_mth(0),age_at_entry(0)ormort_schedule(0); and acommute_disc_conventionthat is neither code, 2 say,invalid commute_disc_convention, wherever a certain month remains to discount.
An argument outside a cache raises IndexError in the compiled model alone, as above:
net_cf(1562) and net_cf(-1), which modelx answers with 0, the month being outside
cover; pols_if_at(0, 3) and claim_pp(0, 3), which modelx refuses as invalid timing
and invalid kind; lives_if_init(3) and death_mth(3), which modelx refuses as
invalid life; cum_annuity_pp(1442), annual_income(122) and surr_charge_rate(122),
which modelx computes, cum_annuity_pp(-1) and annual_income(-1), which modelx reads as
0 and as B(1); and mort_rate_base_at(121, 1), which modelx refuses, naming the age. No
projection makes those calls. 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, omega_age,
mort_table_year, the codes, commute_disc_convention 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, omega_age = 120.7 reading 120, where
modelx computes with the float: omega_age = 120.0 makes proj_len() 696.0 there, and
result_cf() then fails. A text, a NaN, an infinity or an int beyond 64 bits is refused at
once, with TypeError, ValueError or OverflowError: so commute_disc_convention = "simple", which modelx takes and is_disc_compound() refuses, cannot be set compiled at
all. An int set on a double Reference reads as a float compiled, where modelx returns the
int: commute_util_base = 1 gives commute_util_rate(2) 1 in modelx and 1.0 compiled,
where the cell returns the Reference as it is. Each shipped Reference is a value of its C
type, so no shipped number differs. And a Reference set past its domain computes as C
computes, where modelx raises or turns complex: an inflation_rate of 1e300 makes
inflation_factor(24) infinite compiled, where modelx’s power raises OverflowError, and a
cmt10_shift of −1.05, a discount rate below −100%, makes point 5’s commuted_value(0) NaN
compiled and a complex number in modelx.
An annual mortality above 1 is not refused but capped, in both: mort_rate caps the
best-estimate and the rated rates at 1, min(q, 1.0), as SPIA_US_S does. Uncapped, the
monthly rate, 1 − (1 − q)^(1/12), would be complex in modelx and NaN compiled, silently.
Capped, both compute 1. A NaN rate would stay NaN through the cap, in both, as through
every other bound, each of which the compiled model computes as a comparison that keeps
the value unless the bound is smaller, or larger: a NaN mort_ae_factor, set as a
Reference, makes point 8’s mort_rate(0, 1), lives_if(1, 1) and net_cf(0) NaN in both.
But the payment factor’s max(C, L) keeps its first argument when the second is NaN, in
both, so annuity_payments(0) is 0.0 there, a number: which is why Data refuses, on
each point whose projection reads one through such a max, a missing amount or rate.
Speed#
python tools/bench_sec_cy.py immediate_annuity builds the model into a temporary
directory, or takes a build with --build, and times one block run on three engines:
modelx, the export and the compiled model. Each engine runs the committed table repeated,
in a process of its own, as run_sec.py --block runs a block, each point projected and
then released. net_cf is net_cf(t) summed over the frame, the projection alone, as
basiclife/BasicTerm_SC is timed on its pv_net_cf(); result_cf is the report
run_sec.py prints, which builds a DataFrame for each point. Each time is the fastest of
three runs, with their spread in seconds:
Engine |
Points |
|
|
Peak memory |
|---|---|---|---|---|
compiled |
6,006 |
0.808 ms (4.85–5.13) |
1.25 ms (7.51–7.81) |
83 MB |
export |
616 |
7.66 ms (4.72–4.84) |
8.05 ms (4.96–5.14) |
79 MB |
modelx |
132 |
197 ms (26.02–26.74) |
200 ms (26.43–27.70) |
137 MB |
On net_cf the compiled model runs 9.5 times its export, and on result_cf, where building
the DataFrame takes much of its time, 6.4 times; it runs 244 and 160 times modelx. A second
run of the whole benchmark straight after, on a second build of the same files, gave the
compiled model 0.823 and 1.23 ms, the export 7.76 and 8.35 ms and modelx 194 and 203 ms, 9.4
and 6.8 times the export. The compiled model runs fewer times its export than UL_US_SEC,
12.0, or VUL_US_SEC, 13.8, about as many as Term_US_SEC, 9.5: of its 0.81 ms, making and
releasing the ItemSpace, which Python zeroes, takes about 0.26 ms. As it stood after running
in force, compiled the same way, the model ran 2.0 times its export (What compiling
changed, and why, above, measured once on a build not shipped, so not reproducible from the
repository), and the compiled model runs about 10 times that build on the same
measure, 0.76 ms a point over the committed points against 7.57: the representation, not the
compiler, is the gain, and the export gained from it too, 7.37 ms a point against 14.9. The
release keeps a block flat: the compiled model’s peak grew by 2 MB over its 6,006 points,
and without the collection after each release (--no-collect), 506 compiled points peaked
at 540 MB. Reading the four files and building every Data vector and array for those
points took 0.04 s, and asking every point for its frame, the runner’s first pass, 1.7 s,
most of it making and releasing an ItemSpace a point.
Measured on 2026-11-13 on a desktop shared with other work: 12 cores and 20 threads (an Intel Core i7-12700KF), 64 GB, Windows 11; Python 3.13.18, its extensions compiled by MSVC 14.37 (Visual Studio 2022), with modelx 0.33.0, modelx-cython 0.1.0, Cython 3.3.1, numpy 2.5.4 and pandas 3.1.1. Windows reports no load average: sampled every 10 seconds, the processors were 7 to 24% busy during the runs, mostly 10 to 15%, of which the benchmark’s own process, one thread, is 5 points, and a probe of this page’s ran beside the second run’s last modelx runs. Each time is the fastest of three runs; the fastest run is the one to compare. The comparisons over the committed points, with the build as it stood after running in force, are the fastest of three rounds each, in one process an engine, and so is the cost of an ItemSpace, the fastest of five rounds of 1,000.
Tests#
The twin identity, in
tests/test_model_conventions.py: on points 1 to 15, commencing at the valuation date, every cell ofSPIA_US_S’s agrees at every argumentSPIA_US_Sevaluates in its own sweep, but forpols_if_init,model_pointandresult_pols, whose meaning changed;SPIA_US_S’sclaims(t, None)andclaims(t, "REFUND")are compared withclaims(t), through the spec’stwin_arg_map, and its timing and kind strings with the codes. A cell this model lacked would fail it. So the goldenstests/test_immediate_annuity_us.pyasserts on those points — every row of the worked-example table under both triggers, the income levels behind it, the notes’ five traces and the pitfall cases — hold here with no number restated. The identity holds on any count, since neither model charges acquisition. The same suite holds the model to the conventions every_SECmodel meets: every frame starts att = 0, new business joins theBEF_NBcount and enters once at itspolicy_count, nothing happens before the annuity commences, and the in-force columns are present; and toSPIA_US_S’s product fact, that the gross outgo is never negative. The convention thatpols_ifis theBEF_DECRcount is skipped, becausepols_ifis the closing measure (Counts and timings).The splice, in
tests/test_immediate_annuity_us_sec.py: eachSPIA_US_Spoint restated in payment at months either side of its events continues the S projection, inresult_cf, inresult_pols, column by column, and in every other cell the two share, to 1e-9 relative with no absolute floor, which would hide the survival near the limiting age, but for the cells the twin identity skips and the two whose value is a frame length or a time point on the valuation clock,proj_lenandpayment_surv_mth. The months are those S’s events need: the first anniversary and the months either side of it, the worked example’s month of death and the month after, both lives dead, the second withdrawal and the month after the residual floor binds, the last month of each certain period and the first after it, the trim months of the installment refunds, the last month of a frame, either side of the limiting age inside a certain period, and months between quarterly or semi-annual instalments. So do eleven variants of S’s points, in a copy of S’s table that is never committed, for branches S’s own points do not reach: every frequency on both timings, a cash refund on the table basis and one on a joint contract, an installment refund on a COLA path that commutes, one paid in advance, one that never repays its premium and one whose first instalment repays it, the primary trigger on the table basis, rated and commencing in 2020, commutation barred by the issue state, commutation oncertain_only, and a certain period that outlasts the age stop, with premium tax and qualified money. Inflation, the one input on the valuation clock, is set to 0 in both models. Commutation, which ships at zero utilization, is switched on in both at 0.5, and the CMT is set 50 basis points up sinceSPIA_US_S’s annuity dates, itscmt10_shiftat 0.005, because at the shipped zeros neither the commutation fraction nor the CMT’s change shows in any comparison. This model reads the splice’s table once, as a block is read, on one path of the CMT: a point restated in payment has seenSPIA_US_S’s change by the valuation date, and carries it ascmt10_shift_init, and nothing changes after it, so this model’scmt10_shift, the change made at the valuation date, is 0; a point commencing later has seen no change and sees none, so it is compared withSPIA_US_Sread again with itscmt10_shiftat 0, the same contract on that path. In both copies the improvement scale is set apart by age and sex, because the shipped scale is the same for both sexes at every age and flat at 0.01 to age 85, where a join on the wrong sex or age would read the same number. Improvement itself is not neutralized: it is dated by the calendar on the policy clock.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 form, trigger, basis, timing and frequency, every opening-state column at every value it takes, every kind of valuation month and every branch the full grid reaches, and each frequency and timing other than monthly that a refund or commuting point carries is valued off its payment period by some core case; a test asserts all of it. The other cases carry the
sec_fullmarker and show as skipped, with the reason, unlessUSLIB_SEC_FULL=1is set. One leg of the CI matrix sets it, so every CI run runs the full grid too.Future new business: commencing 13 months after the valuation date, more than a year on and off every payment step, each S point and each variant is the S projection moved on, with zeros before the annuity date in
result_cfandresult_pols, no decrement rate evaluated there and neither table read below an issue age; and so are the anchor cell on the table basis and the commuting point commencing 12 months on, and the worked example’s anchor cell commencing a month on.How it computes: on every row the splice and the future business compare, the core by default and the full grid with
USLIB_SEC_FULL=1, after every report, no cell has been called at a negative argument, none evaluated fromt_entry()on has read a month before it, none evaluated at monththas read a month later thant + 1, and every policy-clock and age argument is one the contract has: the payments to date, the schedule, the income, the utilization and the surrender charge from the annuity date to the stop rule, and the two table readers from each life’s issue age to its age in the last month, below the limiting age. On a fresh read of the committed model,duration_mth(500)evaluatesduration_mthonce, because the policy clock is a closed form, and every point is swept under modelx’s recursion limit lowered to 40, which a recursion backward over the frame would exceed. And a coldnet_cfin the last month runs no deeper than one cell a month back tot_entry(), plus a fixed overhead, on the anchor cell’s twins on both bases, on the cash refund in payment 13 months and at the longest cover the product allows.Counts, validation and regeneration: the count is on the books from the annuity date to the stop rule, and
pols_if_atrefuses a timing it does not have;pols_ifis the closing obligation measure on that count;result_pols()isSPIA_US_S’s, column for column, withpols_new_bizbeside it; multiplyingpolicy_countby 2.5, a count that is not whole, with commutation and the CMT’s change switched on at the splice’s values, multiplies every cash flow, the surrender charge and the counts at each timing, and moves no per-contract value. Each malformed row is refused naming its point, each on a model read for it and again through a projection, and each by the one rule under test: among them a count, a duration, a probability, a fraction or a CMT change that is not a number, a state other than the annuity date’s on a contract not yet in payment, a second life on a single-life contract, a month of death written as text or as a fraction, on either basis, a scenario life whose status is not its month of death’s, and a commutation fraction where none could have been taken, a certain period of 0 months among them. A malformed surrender-charge scale is refused naming the file, the same way, and one written as floats is read by value. Each kind of contract owing nothing, and a point at or past the stop rule, is refused byproj_len()with its message, andrun_sec.py --blockrefuses such a table before printing anything; the horizon is a Reference, which at 0 refuses any future business, saying so; an unknown form, trigger, timing, basis, frequency or discount convention is refused where the projection meets it, and so are a third life, a claim kind and a timing neither model knows; a zero count, integer columns written as floats, an annuity commencing 120 months on, a month of death written as −1 on a living life, a commutation fraction from policy month 13, a fall in the CMT since the annuity date and a fraction past the residual floor are accepted; and the committed table is whatSPIA_US_Sgenerates.The opening state and the rest: the derived rows carry the worked example over at the valuation date, with the figures above; each life’s survival opens at its column and runs on as
SPIA_US_S’s does; the payments to date areSPIA_US_S’s at every key, read on a fresh model from the valuation date’s policy month on; the commutation fraction carries over in force, and zeroed gives the figures above; at a utilization of 1 the residual floor caps a withdrawal in force, leaving the smallest certain instalment at $100, which the splice’s 0.5 never does; the simple discount convention continuesSPIA_US_Stoo; three contracts in one table, in payment, commencing at the valuation date and commencing later, read each the CMT’s change since its own annuity date, on one path, withcmt10_shiftat 0 and at 0.005, the last unmoved by it; improvement is dated by the calendar on the policy clock; where a cap on mortality binds, at the limiting age on the anchor’s twin and on rows in payment, one of them rated past 1 at 117, the annual and monthly rates are the float 1.0, every life alive at the start of the month dies in it, and every report is float64 and finite; a NaN sent to either cap, throughmort_rate_base’s orrating_factor’s formula replaced, stays NaN; expense inflation runs on the valuation clock at the shipped 2.5%, which only this test sees, since the splice sets the rate to 0; an annuity commencing later brings no premium and no acquisition cost; the model haspols_new_bizand no lapse; the stop rule ends every frame; every guarded cell holds its value outside the frame and reads no rate there; the points of a block sum row by row; an extract without the generator’s three columns, relabelled and reversed, projects the same numbers;run_sec.pyprints the model’s numbers, for a point commencing at the valuation date, one in payment, one in its last month, a one-row frame its headings call one row, one commencing later and the block; the docstrings describe the valuation clock and map every cell running in force adds; and the model readsSPIA_US_S’s assumption tables in place.The fingerprint (C2): before the compile step changed anything, what the model computed on each committed point was frozen in the module, each column of
result_cf()andresult_pols(), its sum, its largest value and its values at five months, and the model reproduces it to 1e-12.python tools/gen_sec_fingerprint.py SPIA_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 the discount convention, andclaims(t)forclaims(t, kind). Each point is named by its label, inpoint_id(), in a refusal and inrun_sec.py’s output.What compiling changed: each value a point’s projection cannot use, text, a blank or infinite amount or rate where a
max, aminor a search reads it, an intint()cannot read or of2**53or more in size, is refused by the point’s own accessor, in a projection and by a direct call, naming the point, while the table reads and every other point projects the committed numbers exactly, a point holding the same value outside the accessor’s scope among them; a fraction in an issue age, a certain period or an annuity year truncates, asSPIA_US_S’sint()does, and the point projects the committed numbers; a point issued belowissue_age_min, 0, on a lifetime form or thecertain_onlyform, a joint annuitant on each among them, and a certain period above 1,440 months are refused byproj_len(), naming the point, and each projects once its bound is moved; acertain_onlyannuity at issue age 0, the longest cover the caches hold, and at 17, a single life annuity at 17 and a joint life annuity whose joint annuitant is issued at 0, below the 18product-spec.mdissues lifetime forms at, project, and each but the second isSPIA_US_S’s in every cell; on an improvement scale holding a sex the mortality table lacks, both written out of their keys’ order, each table is numbered by its own sexes, each life reads its own sex’s row, and the points project the committed numbers; the padding beyond each table’s extent is NaN, each reader refuses an age below its table’s first, and a sex the table lacks is refused at the first age read, where a point on the scenario basis with the same sex projects; on tables whose sexes start at different ages, each reader reads within its own sex’s ages and refuses an age below them, naming the point, the age and the life; everyDatacell but the readers is the int64 or float64 array, or the int, that theDatadocstring’s table states; each size inspec_sec.pyis the one its comment derives from the model’s References, every 2-D cache one inner width, and the codes dense from 0, the sample’s recursion limit is the one its comment derives, and the sample callssexon a second instance whose table’s sexes are blank; and outside the repository, beside a copy of the model or at a path too shallow to hold one,run_sec.py --cythonsays it cannot build.No pandas in
Projection(C5), intests/test_compiled_conventions.py, which holds what every_SECmodel meets once it compiles. Read from the formulas, with no compiler: no cell but the reporting ones refers to pandas, numpy or another module, reads a table with.locor the like, calls a reporting cell, holds text but in its docstring and its refusals, or holds a generator, a comprehension or a nested function; none calls anything but a cell, aDatavector and the builtins of No Python call kept, and the registry admits no other for this model; everyDatavector a formula reads is an int64 or float64 array, read by element; no cell is uncached; and each label accessor returns its point’s column on every point, of its own name or as the registry’s"reporting_columns"names it, and each such entry is needed.Compiled, where modelx-cython and a C compiler are installed, after compiling the model once into a temporary directory, never into the tree. In the same conventions module: the generated declarations give every cell but the reporting ones a C
bint,long longordoubleand a C-array cache of exactly the spec’s size, and every newDatacell but a reader a typed memoryview or a C scalar, and the generated C keeps no Python object among a projection cell’s locals, calls no Python builtin there, and builds no container, under both directives (C3); on the committed points, every cell at every argument a full modelx sweep caches is what modelx computes, bit for bit on x86-64, and so is every raise and everyDataarray (C4); andrun_sec.py --block, run compiled, holds one point’s ItemSpace at a time. Intests/test_immediate_annuity_us_sec.py: the same comparison on the splice grid, the core by default and the full grid withUSLIB_SEC_FULL=1, twenty rows at a time, each life’s death density with every other cell; at the contract’s extremes, the longest frames, the youngest and oldest issue ages and the longest certain period, on age tables extended to age 0 with a value of their own at every age and sex; where the residual floor binds, and its cap on the fraction commuted is reached, and under the simple discount, each set through References and first shown to bind in modelx; where the cap on mortality binds, and where a NaN A/E reaches it; on keys written as floats, where everyDataarray is first held to its dtype and values on the keys as written, in modelx, in seconds; and on a sex that is a number or blank, whichsexreturns as modelx does; the compiled model refuses what modelx refuses, with modelx’s message, on the relabelled extract, every refusal of the module among them, and an argument past a cache, either side, raisesIndexError; the deepest call the contract allows runs cold on a 1 MiB stack and on the main thread, and the test reports the smallest of nine stacks, 256 KiB to 2 MiB, it ran on, waiting a bounded time for each; a Reference set after the model has computed changes no value it has cached; andrun_sec.py --cythonprints whatrun_sec.pyprints, and refuses a directory that holds no build. They are markedcython, and they skip without the toolchain, but in thecythonCI job, which installs it on Linux and on Windows, one leg a product, a skip fails, whatever made it.
python -m pytest tests/test_immediate_annuity_us_sec.py -q
USLIB_SEC_FULL=1 python -m pytest tests/test_immediate_annuity_us_sec.py -q # full grid
python -m pytest tests/test_model_conventions.py -q -k "[SPIA_US_SEC]"
python -m pytest tests/test_compiled_conventions.py -q -k "[SPIA_US_SEC]"
python -m pytest tests/test_immediate_annuity_us_sec.py -q -m cython # the compiled tests