Source code for uslib.products.indexed_ul.IUL_US_SEC.Projection

# modelx: pseudo-python
# This file is part of a modelx model.
# It can be imported as a Python module, but functions defined herein
# are model formulas and may not be executable as standard Python.

"""The by-policy monthly projection of the :mod:`~.IUL_US_SEC` model.

The Space is parameterized by ``idx``, the position of a model point in the table and in
every :mod:`~.IUL_US_SEC.Data` vector, as ``basiclife.BasicTerm_SC`` is: ``Projection[6]``
is an ItemSpace projecting the table's seventh row, model point 7, ``IUL_US_S``'s
monthly-premium point restated 65 months on, in force at the valuation date with all
twelve index segments live, and :func:`point_id` is its label::

    >>> Projection[0].result_av()          # the account value roll-forward
    >>> Projection[6].result_seg()         # the segment ladder, carried in
    >>> Projection[6].point_id()           # 7, the row's point_id
    >>> Projection.idx = 1                 # or switch the default, before it computes

Compiled, no cache is ever cleared: set ``idx``, like every Reference, on a model just
imported, before anything is computed, or project through ``Projection[i]``. modelx
recomputes what a Reference reaches when it is set; a compiled ItemSpace takes the
References when it is made and keeps every value it has computed until it is deleted,
and the base ``Projection`` and ``Data`` keep theirs for good. And it holds each Reference
as a C variable of its shipped value's type: a float set on an int Reference truncates
toward zero, an int set on a float Reference reads as a float, and text set on a code,
``basis`` or ``seg_credit_base_conv``, is refused with ``TypeError`` at assignment, where
modelx's cell refuses it as it reads it (``products/indexed_ul/model-sec.md``).

Any ``idx`` makes an ItemSpace, and none is refused here. ``Projection[-1]`` reads every
vector at its last element, as numpy and a compiled memoryview both do, so it is the
table's last point, under that point's own :func:`point_id`; an ``idx`` past the last
row raises ``IndexError`` at its first read of a vector, which modelx reports inside its
``FormulaError``.

This is :mod:`~.IUL_US_S` taught to run in force at a valuation date, as lifelib's
``basiclife.BasicTerm_SE`` extends ``basiclife.BasicTerm_S``, and then made to compile, as
``basiclife.BasicTerm_SC`` is made from ``basiclife.BasicTerm_S``. A formula of
:mod:`~.IUL_US_S` is rewritten where it depends on the month its frame opens at, where it
must answer for a month outside cover, where it reads the index path, or where it reads a
table at a policy year or an attained age; every other is :mod:`~.IUL_US_S`'s own.
``products/indexed_ul/model-sec.md`` lists the rewritten cells with the reason for each.
Making it compile changed how each cell reads its inputs and spells its codes, and no
number: every model point attribute a projection cell uses is read as a number from a
``Data`` vector, every table as an array indexed by integers, the segment ladder among
them, every timing and kind is an int code, and so are the basis and the credit base's
convention (*Codes*, below). :mod:`~.IUL_US_S`'s ``coi_rate_scale``, a Series, is a
schedule number, :func:`coi_schedule`; its ``claims(t, kind=None)`` is two cells and
their total, :func:`claims_death`, :func:`claims_lapse` and :func:`claims`; its six
segment cells keyed by a segment's creation month, ``seg_bal_pp(t, m)`` and its
neighbours, are keyed by the segment's slot, its months since creation,
``seg_bal_pp(t, k)`` (*The segment ladder*, below); and its crediting engine, five cells
of float arguments, is inlined into cells keyed by the month, :func:`seg_return`,
:func:`seg_credit_rate` and :func:`index_credit_pp`, the five kept for its worked example
and called by no projection cell (*Reporting cells*, below).

.. rubric:: Input data

Inputs are **external files**: plain CSVs living in the model folder's parent
directory, ``products/indexed_ul/``, read at run time rather than stored inside the
model. The model folder therefore holds nothing but formulas -- no ``_data/``, no
IOSpec, no embedded values -- so a diff of the model shows logic changes only, and an
input can be edited or swapped without rewriting the model. This follows
``annuallife.TradLife_A``; contrast ``basiclife.BasicTerm_S``, which keeps its inputs
*inside* the model through modelx's IOSpec machinery.

The consequence worth knowing: **the model is not portable on its own.** Copying the
``IUL_US_SEC`` folder without its parent's CSVs produces a model that reads and then
fails on first evaluation.

The readers live in the unparameterized :mod:`~.IUL_US_SEC.Data` Space, reached here
through the ``data`` Reference, so each file is read once per model rather than once
per model point. The six assumption tables are the files :mod:`~.IUL_US_S` reads, read
in place; the model point table and the segment ladder are this model's own:

======================  ================================  ==========================
Reference (on Data)     Cells                             File
======================  ================================  ==========================
model_point_file        data.model_point_table()          model_point_table_sec.csv
inforce_segments_file   data.inforce_segments()           inforce_segments_sec.csv
coi_rates_file          data.coi_rates()                  coi_rates.csv
corridor_file           data.corridor_factors()           corridor_factors.csv
mort_table_file         data.mort_table()                 mort_table.csv
class_factor_file       data.class_factor_table()         class_factor_table.csv
lapse_table_file        data.lapse_table()                lapse_table.csv
surr_charge_file        data.surr_charge_table()          surr_charge_table.csv
======================  ================================  ==========================

The index path is **not** a file. The base deterministic run generates
:func:`index_level` from a level annual return, and a historical or simulated path is
substituted by overriding that one cell, before the model computes anything: a formula
override, which only modelx can make; compiled, the path is changed by editing the
formula and rebuilding.

.. rubric:: Two clocks

``t`` counts months from the **valuation date**, 0-based, the clock
``basiclife.BasicTerm_SE`` runs on: ``t = 0`` is the valuation month for every model
point, however old the policy, month ``t`` runs from the monthiversary at time ``t`` to
the next, and the frame is ``t = 0, 1, ..., proj_len() - 1``, where :func:`proj_len`
counts the months from the valuation date to the end of the projection. Row ``t`` is the
same month for every point, so the frames of a block line up and sum row by row.

``duration_mth(t)`` counts **policy months**, the notes' own month index from issue:
``duration_mth(t) = duration_mth_init() + t``, where :func:`duration_mth_init` is read
from the model point -- positive for a policy in force at the valuation date, in any month
of its policy year, 0 for one issued at it, ``-k`` for one issued ``k`` months later, at
most ten years later. Everything contractual reads it: the anniversary premium
(``duration_mth(t) % 12 == 0``), the first policy years of the withdrawal and the loan,
the maturity of a segment twelve policy months after its creation, the surrender charge's
month, the no-lapse period and its expiry shock, the GPT and 7-pay years, the COI scale
and the lapse table by policy year, the mortality rate and the corridor factor at the
attained age, the policy-year steps of the per-unit charge and of the collateral's
credited rate, the cessation of premiums and charges at ``charges_cease_age`` and the end
of the projection at ``maturity_age``. The policy year is the 1-based contractual label
``policy_year(t) = duration(t) + 1`` and the attained age (ANB) is
``age(t) = age_at_entry() + duration(t)``, both derived and never indexed by. Point 7,
``IUL_US_S``'s point 4 restated 65 months on, is in policy year 6 at attained age 50 at
``t = 0``, and point 12, to be issued 25 months after the valuation date, is issued at
``t = 25``.

``IUL_US_S`` already counts its months from the start of its own projection rather than
from issue, but ships no point in force, and its in-force entry loses what a policy's past
has left it: it opens the fixed account at the account value less the loan, the loan
collateral at the loan, the face at issue, both premium accumulators at 0, and no index
segment before its first month. 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 its whole state: the fixed account and the collateral apart from the loan, the
face in force, the premiums paid to date and the no-lapse accumulator, whether it has
failed the 7-pay test, and its live index segments.

The economic inputs read the valuation clock. The index path,
``index_level(t) = index_level_init x (1 + index_return_ann)^(t / 12)``, is one path for
every point, whose level at the valuation date is ``index_level_init``; ``IUL_US_S``
reads it at ``duration_mth(t)``, a path of each point's own from its issue. The cap in
force (:func:`index_cap_at`) and the fixed-account rate (:func:`fixed_rate_ann`) are read
at ``t``, and are level as shipped. Expense inflation is
``inflation_factor(t) = (1 + inflation_rate)^(t // 12)``, ``IUL_US_S``'s step by policy
year moved onto ``t``, so that the maintenance expense is in valuation-date dollars for
every point alike; it is 0 as shipped. Acquisition is charged per policy issued, in the
issue month, and is not inflated, as in ``basiclife.BasicTerm_SE``. The collateral's
credited rate and the per-unit charge step on the policy year, as terms of the contract.

A segment's credit is a ratio of two index levels, its level at maturity over its level at
creation, so moving the path onto the valuation clock moves no credit. A segment created
in the frame, at month ``t - 12``, reads ``index_level(t - 12)`` and the cap declared then,
``index_cap_at(t - 12)``; a segment created before the valuation date carries its start
level on the same path, the level ``IUL_US_S`` reads at its creation rebased so that the
path's level at the valuation date is ``index_level_init``, and the cap declared at its
creation (:func:`seg_index_start`, :func:`seg_index_cap`). What does move is the level
itself: on a point in force ``d`` months, ``index_level(t)`` is ``IUL_US_S``'s level at its
month ``t + d`` divided by ``(1 + index_return_ann)^(d / 12)``, and so is the
``index_level`` column of :func:`result_seg`.

On a point issued at ``t = 0`` the two clocks coincide and this model computes what
:mod:`~.IUL_US_S` computes: every cell the two share agrees at every argument
:mod:`~.IUL_US_S` evaluates in its sweep, but for four whose meaning changed:
``pols_if_init``, now the count already in force at the valuation date, ``model_point``,
a row of another table, ``result_pols``, which gains the month's new business, and
``check_margin``, whose identity this model states with the debt a surrender recovers (see
:func:`check_margin`). ``tests/test_model_conventions.py`` asserts it cell by cell.

The **value** state variables are closing balances at the end of month ``t``, the notes'
``X_{t+1}``: :func:`av_pp`, :func:`fa_pp`, :func:`lca_pp`, :func:`loan_bal_pp`,
``seg_bal_pp(t, k)``, :func:`sum_assured_at`, and the two premium accumulators,
:func:`cum_prem_pp` and :func:`cum_prem_net_pp`. The opening value of a month, the notes'
``X_t``, is the ``BEF_PREM`` timing of :func:`av_pp_at`, :func:`fa_pp_at` and
:func:`lca_pp_at`, or the previous month's value of the others, and at :func:`t_entry`,
the first month on the books, the model point's opening state instead, so that nothing is
ever asked for a month before the valuation date or before issue. For a point in force the
opening state is its row and its segments, per policy, as the policy stands at the start
of month 0, before any month-0 event: the account value and the loan, ``IUL_US_S``'s own
columns (:func:`av_pp_init`, :func:`loan_bal_init`); the fixed account and the loan
collateral (:func:`fa_pp_init`, :func:`lca_pp_init`); the face in force
(:func:`sum_assured_init`); the premiums less withdrawals paid to date and the no-lapse
accumulator, premiums less withdrawals and loans (:func:`cum_prem_init`,
:func:`cum_prem_net_init`); the MEC latch (:func:`is_mec_init`); and each live segment's
balance, deductions and draws to date, start level and cap, from the segment ladder (see
*The segment ladder*, below). At a mid-year valuation the current year's anniversary
premium and loan draw are already inside them. For a point issued at or after the
valuation date every one of them is 0, and the issue values come from the formulas, as
in ``IUL_US_S``.

Every chain is one cell a month. Each opening timing forms the previous month's close
itself, from its own value at ``t - 1`` and month ``t - 1``'s premium, credit, draws,
deduction, sweep and interest, the same operations in the same order as the closing cell
``IUL_US_S`` calls for, rather than calling for it: the account value's, where
``IUL_US_S``'s chain ran through five cells a month, the fixed account's, through six,
and the collateral's, through two. The loan, the face, the two premium accumulators, the
MEC latch, each segment's balance and running totals, and the count call themselves at
``t - 1``, one cell a month. A compiled model runs these chains on the C stack.

Within each month the notes' monthiversary order is followed exactly:

1. **Anniversary resets and premium.** The attained age and the corridor factor move
   on the policy anniversary (:func:`age`, :func:`corridor_factor`); the annual
   premium is received at BOM of the first month of each policy year and its load
   deducted (:func:`premium_pp`, :func:`prem_to_av_pp`), the net premium going to the
   fixed account.
2. **Segment maturity.** A segment created twelve months earlier matures: its index
   credit is computed (:func:`index_credit_pp`) and its whole value rolls into the
   fixed account (:func:`seg_roll_pp`), from which the sweep at step 7 re-enters it
   into a new segment under the standing instruction **[std]**.
3. **Withdrawals and new loans** are sourced fixed-account-first, then pro rata across
   live segments (:func:`draw_from_fa_pp`, :func:`draw_from_seg_pp`) -- the order one
   carrier gives for loans [S3]; for withdrawals, which that carrier takes pro rata
   across all unloaned accounts [S3], it is **[std]**; loan
   collateral moves into :func:`lca_pp`.
4. **Death benefit and corridor** on the post-premium, post-withdrawal account value
   (:func:`db_pp`).
5. **Net amount at risk**, the death benefit discounted one month at the
   **guaranteed** rate less the account value measured **before** the deduction
   (:func:`net_amt_at_risk`) -- the universal life base convention.
6. **Monthly deduction** (:func:`mth_deduction_pp`), sourced the same way as step 3
   (:func:`mth_deduction_from_fa_pp`, :func:`mth_deduction_from_seg_pp`), then the
   shortfall / no-lapse test (:func:`is_shortfall`).
7. **Sweep.** ``w_ix`` times the remaining fixed-account balance creates the new
   segment of this month (:func:`sweep_pp`, :func:`seg_new_pp`).
8. **Interest, EOM.** One month at the fixed-account rate on the post-sweep fixed
   balance and at the loan collateral rate on the collateral account
   (:func:`inv_income_pp`); **segments earn no interim interest** [S2]; loan interest
   accrues (:func:`loan_bal_pp`).
9. **Decrements, EOM**, death before lapse (:func:`pols_death`, :func:`pols_lapse`).

Cash flows are **undiscounted**. Premiums, expenses and premium taxes fall at BOM and
are weighted by :func:`pols_if`, the count in force at the **start** of month ``t``;
death claims by ``pols_if(t) * mort_rate_mth(t)``; surrender payments by
``pols_if(t) * (1 - mort_rate_mth(t)) * lapse_rate_mth(t)``; and partial withdrawals by
``pols_if(t)`` again, because a withdrawal is taken at BOM on the owner's election and
is not a decrement.

.. rubric:: Counts

``pols_if(t)`` is the count that weights row ``t``: ``pols_if_at(t, BEF_DECR)``, the
count carried in from ``t - 1`` (``BEF_NB``) plus the month's new business,
:func:`pols_new_biz`, before the month's decrements. A point in force at the valuation
date opens with :func:`pols_if_init`, its ``policy_count``; one issued at or after the
valuation date opens with none, and takes its ``policy_count`` as new business in its
issue month. The recursion's base is :func:`t_entry`, and before issue
(:func:`is_active`) every count, and so every cash flow, is zero, and so is every value
state. ``IUL_US_S`` already names three timings, in a cell that returns ``pols_if(t)``
for each and that nothing calls. ``BEF_DECR`` keeps that meaning, and so does
``BEF_MAT``, the count before any maturity, since nothing matures: the name keeps its
S model's meaning, as in the family's other models, and ``basiclife.BasicTerm_SE``'s
start-of-month ``BEF_MAT`` is not adopted. ``BEF_NB`` is the one timing this model
gives a new meaning, ``basiclife.BasicTerm_SE``'s, and it differs from ``IUL_US_S``'s
only in the issue month, where it counts the issued policies as new business, not yet
in. Inside the month the decrements are :mod:`~.IUL_US_S`'s, in its order: death, then
surrender. No policy is terminated for insufficiency, as in ``IUL_US_S``.

.. rubric:: The end of the projection

The frame ends at :func:`maturity_mth`, the policy month at attained age
``maturity_age``, 121, the notes' [unverified] maturity inference (spec F5), and not at an
event of the contract, which is described as continuing in force with no further charges
at 121. Premiums, withdrawals and charges stop at ``charges_cease_age``, a Reference of
its own, 121 too as shipped; set below ``maturity_age``, the projection runs on past the
cessation, the account value earning its interest and the segments their credits with
nothing deducted. The roll-forwards read the survivors of the last month:
:func:`check_av_roll_fwd` and :func:`av_change` read the opening account value in force
of month ``t + 1``, which in the last month is ``t = proj_len()``. So the two opening
values they read there, the count (the ``BEF_NB`` timing of :func:`pols_if_at`, and
through it :func:`pols_if`) and the account value (``av_pp_at(t, BEF_PREM)``), are
defined for ``0 <= duration_mth(t) <= maturity_mth()``: on the books, and in the month
after the frame, where they are the survivors of the last month and the account value they
carry. Each equals :mod:`~.IUL_US_S`'s value there exactly. Every other cell is zero or
false there, as before issue: each account inside the month and its opening value, each
segment, the loan, the face, every charge, premium, withdrawal, loan draw, credit,
decrement rate, decrement, claim and flow, and the expenses, whose maintenance would
otherwise fall on the carried count; only the two clocks, the inputs read on the valuation
clock and the neutral 1.0 of the two lapse multipliers hold values there. And nothing
reads past ``t = proj_len()``: :func:`av_change` and the residual cells of the checks,
which read ``t + 1`` or are read beside cells that do, are zero outside cover before they
read it.

.. rubric:: The segment ladder

A segment is created at every monthiversary from the sweep and matures twelve months
later, so between step 2 and step 7 of any month eleven segments are live and after the
sweep twelve are -- the "up to 12 segments" of [S4]. A segment is born in a policy month
``m``, ``duration_mth`` of the month of the sweep that created it, and in month ``t`` it
sits in **slot** ``k = duration_mth(t) - m``, its months since creation, 0 in its creation
month and 11 in the last month it is live: ``seg_bal_pp(t, k)`` is the balance at the end
of month ``t`` of the segment ``k`` months old then, and is zero outside
``0 <= k <= min(11, duration_mth(t))``. The six cells of a segment in a month,
:func:`seg_share`, :func:`seg_wd_pp`, :func:`seg_ded_pp`, :func:`seg_bal_pp`,
:func:`seg_ded_cum_pp` and :func:`seg_wd_cum_pp`, are keyed so, by ``(t, k)``, and each
reads its own value of the month before at ``(t - 1, k - 1)``, the same segment a month
younger: ``IUL_US_S`` keys them by ``(t, m)``, which a compiled cache would hold across
every creation month of the frame, where twelve slots hold the live ones. A segment's
creation balance, :func:`seg_new_pp`, is keyed by its creation month ``m``, a policy month,
as in ``IUL_US_S``: one value a segment. A parameter that holds a policy month is named
``m``, never ``t``, so that what moves with the valuation clock is ``t`` alone.

A point in force at the valuation date carries its live segments in a companion of the
model point table, ``inforce_segments_sec.csv``, one row a segment, keyed by ``point_id``
and ``slot``: the months since the segment's creation at the valuation date, 1 to 12, so
that the segment in slot ``k`` is the one born in policy month ``duration_mth_init() - k``
and the segment in slot 12 matures at ``t = 0``. The ladder's slot is the slot of month
0, so a segment carried in opens at ``t = 0`` from its own row: ``seg_bal_pp(0, k)``
from ``seg_bal_pp_init(k)``. Every month of the last
``min(12, duration_mth_init())`` holds a row, a month that swept nothing included, at
zero, since the credited rate of a month reads the start level and the cap of the segment
maturing then whether or not it holds a balance (:func:`cred_rate_ann`). Each row gives
the segment's balance entering month 0 (:func:`seg_bal_pp_init`), the deductions and the
draws -- withdrawals and loan transfers -- charged to it since its creation
(:func:`seg_ded_cum_pp_init`, :func:`seg_wd_cum_pp_init`), which with the balance are its
credit base, the index level at its creation on the valuation-clock path
(:func:`seg_index_start_init`) and the cap declared then (:func:`seg_index_cap_init`). Its
creation balance takes no column: nothing may enter or leave a segment but a deduction, a
withdrawal or a loan transfer, so it is the three summed, which is the closure
:func:`check_seg_ladder` asserts (:func:`seg_new_pp`).

Two properties of this arrangement are worth stating because the notes list both as
pitfalls.

Each segment carries **its own index start level**, so twelve segments a year mature at
twelve different point-to-point returns. Collapsing them into one annual segment
mis-times credits and distorts mid-segment surrender values [S3]; :func:`check_seg_ladder`
and model point 3 (indexed allocation 0%) exist so the difference is visible rather than
assumed.

Deductions and withdrawals are sourced from the fixed account first and then **pro rata
across live segments** on their remaining balances **[std]**. Because a pro-rata draw
leaves the proportions unchanged, one set of shares (:func:`seg_share`) serves both the
step-3 draw and the step-6 deduction. The two claims on the pool are **ordered, not
parallel**: the step-6 deduction is capped against what the step-3 draw leaves behind,
so their sum can never exceed the pool, no segment balance can go negative, and no
segment can pay a negative index credit at maturity. Capping both against the same
pre-draw pool is the easy mistake, and :func:`check_seg_ladder` asserts against it.
The credit base under the baseline convention is exactly the remaining balance --
amounts that left the segment mid-term earn no index credit [S3]. The alternative
convention the notes price, one carrier's adjusted-beginning-value with half-weighted
deductions [S3], is the ``ADJ_BEGIN`` argument of :func:`seg_credit_base`.

A segment can close a month on a rounding about zero, a balance of the order of 1e-16 of
either sign, where a draw or a deduction took exactly what it held. :func:`seg_share` and
:func:`seg_count` read such a balance by ``IUL_US_S``'s own tests of zero, and the pool
:func:`seg_bal_active_pp` and the total :func:`seg_bal_tot_pp` sum the segments in an
explicit loop that compensates as Python's ``sum()`` of floats does from Python 3.12, so
that each is ``IUL_US_S``'s sum bit for bit there. Python 3.11's ``sum()`` is a plain
fold, which can leave such a pool on the other side of zero, so the states ``IUL_US_S``
closes on a rounding about zero depend on the interpreter it runs on.

.. rubric:: Naming

Cell names follow :mod:`~.UL_US_S` -- the chassis these notes defer to -- and
through it lifelib's ``basiclife.BasicTerm_S`` and ``savings.CashValue_SE``: ``pols_*``
for policy counts, ``av_*`` for account values, plural nouns for cash flows, ``*_rate``
for rates, ``*_pp`` for per-policy amounts, ``timing`` and ``kind`` arguments.
Every concept shared with the chassis carries the chassis name. The names that are new
in ``IUL_US_S`` are the ones the indexed crediting engine needs: the fixed (holding)
account, the segment ladder, the crediting formula, and the no-lapse guarantee test.

What running in force adds is named as ``basiclife.BasicTerm_SE`` names it:
``duration_mth`` read from the model point, ``policy_count``, ``pols_new_biz``,
``pols_if_at`` with its ``BEF_NB`` timing, ``is_active`` and ``result_pols``.
``t_entry``, the first month on the books, is the SEC models' own, and ``maturity_mth`` is
named for ``maturity_age``, where the projection ends. A column of the opening state is
the cell it opens with ``_init`` added: ``av_pp_init`` and ``loan_bal_init`` are
``IUL_US_S``'s own, and ``fa_pp_init``, ``lca_pp_init``, ``sum_assured_init``,
``cum_prem_init``, ``cum_prem_net_init`` and ``is_mec_init`` open :func:`fa_pp_at`,
:func:`lca_pp_at`, :func:`sum_assured_at`, :func:`cum_prem_pp`, :func:`cum_prem_net_pp`
and :func:`is_mec` as they open theirs. A column of the segment ladder is the segment
cell it opens with ``_init`` added, keyed by the slot: ``seg_bal_pp_init(k)``,
``seg_ded_cum_pp_init(k)`` and ``seg_wd_cum_pp_init(k)``; the start level and the cap,
which no cell of ``IUL_US_S`` holds per segment, are ``seg_index_start_init(k)`` and
``seg_index_cap_init(k)``, and the monthly cells that read them, for the segment maturing
in month ``t``, :func:`seg_index_start` and :func:`seg_index_cap`. A table read at an
attained age has one reader keyed by the age, ``<cell>_at(a)``, and a table read at a
policy year one keyed by the year, ``<cell>_py(y)``; the monthly cell keeps
``IUL_US_S``'s name and calls its reader inside cover. The surrender-charge schedule,
keyed by its ID, has one reader for each of its two columns, :func:`surr_charge_rate_max`
and :func:`surr_charge_runoff_years`. A check's residual in month ``t`` is
``<check>_resid(t)``. Each text column a monthly cell branches on is read through bool
decodes, one for each value, named for the value: :func:`is_db_option_a`,
:func:`is_db_option_b`, :func:`is_gpt`, :func:`is_level_premium`,
:func:`is_single_premium`, :func:`is_target_premium`, :func:`is_annual_premium` and
:func:`is_monthly_premium`. Each reads the vector ``Data`` decoded from its column, and
so does each per-point join, so no projection cell compares text or calls a label
accessor: ``IUL_US_S``'s label accessors, ``sex``, ``rate_class``, ``db_option``,
``qual_test``, ``premium_type``, ``premium_mode`` and ``surr_charge_id``, are kept as they
are, for reporting (*Reporting cells*, below). A segment's cell in a month is keyed by
its slot, ``k``, and a monthly cell of the segment maturing in month ``t`` is named for
the segment, ``seg_*(t)``: :func:`seg_return`, :func:`seg_credit_rate`,
:func:`seg_index_start` and :func:`seg_index_cap`.

=========================  ==============================  ==========================
Notes symbol               Cells                           Meaning
=========================  ==============================  ==========================
t                          (the ``t`` argument)            Months from the valuation
                                                           date, 0-based
(months at valuation)      duration_mth_init               Completed policy months at the
                                                           valuation date; -k if issued k
                                                           months later
(notes' t, from issue)     duration_mth(t)                 Completed policy months at
                                                           month t
y                          policy_year(t)                  Policy year, 1-based,
                                                           ``duration(t) + 1``
(y - 1)                    duration(t)                     Completed policy years at BOM
(model point)              point_id()                      The point's label
(issue age)                age_at_entry                    Issue age (ANB)
Sex                        sex                             Sex, M or F
Risk class                 rate_class                      Underwriting class, spec
                                                           Table 1
DB option                  db_option                       Death benefit option, A or B
(Option A)                 is_db_option_a                  Whether db_option is A
(Option B)                 is_db_option_b                  Whether db_option is B
Tax test                   qual_test                       IRC 7702 test; only GPT
                                                           modeled
(GPT elected)              is_gpt                          Whether qual_test is GPT
Premium mode               premium_mode                    ANNUAL **[std]** or MONTHLY
(annual mode)              is_annual_premium               Whether premium_mode is ANNUAL
(monthly mode)             is_monthly_premium              Whether it is MONTHLY
x                          age(t)                          Attained age (ANB)
(none)                     proj_len                        Months from the valuation date
                                                           to the end of the projection
(projection end)           maturity_mth                    Policy month the projection
                                                           ends at, attained age 121
(none)                     t_entry                         First month on the books
(none)                     is_active(t)                    Whether month t is in cover
(none)                     policy_count                    Policies the model point
                                                           stands for
F                          sum_assured                     Initial face amount
F_0                        sum_assured_init                Face in force entering month 0
F_{t+1}                    sum_assured_at(t)               Face after reductions, end of
                                                           month t
F/1000                     units(t)                        Face in $1,000 units
P_t                        premium_pp(t)                   Gross premium per policy
(planned)                  premium_pp_ann                  Planned annual premium
(premium pattern)          premium_type                    LEVEL, SINGLE or TARGET
(LEVEL pattern)            is_level_premium                Whether premium_type is LEVEL
(SINGLE pattern)           is_single_premium               Whether it is SINGLE
(TARGET pattern)           is_target_premium               Whether it is TARGET
(persistency)              prem_persistency(t)             Paid/planned factor 0.98^(y-1)
l_prem                     load_prem_rate()                Premium load rate
NP_t                       prem_to_av_pp(t)                Net premium to the accounts
W_t                        wd_pp(t)                        Partial withdrawal, gross of
                                                           fee
(planned W)                wd_pp_mth                       The wd_pp column, a month's W
(the $25 fee)              wd_fee_pp(t)                    Withdrawal fee
B_t                        loan_new_pp(t)                  New standard loan
(planned B)                loan_new_pp_ann                 The loan_new_pp_ann column
W_t + B_t                  draw_pp(t)                      The whole step-3 draw
W^FA_t + B^FA_t            draw_from_fa_pp(t)              Step-3 draw sourced from FA
W^seg_{k,t} + B^seg_{k,t}  draw_from_seg_pp(t)             Step-3 draw sourced from
                                                           segments
(segment k's share)        seg_wd_pp(t, k)                 Segment k's part of that draw
(cumulative)               seg_wd_cum_pp(t, k)             Draws out of segment k to date
FA_{t+1}                   fa_pp(t)                        Fixed (holding) account, end
                                                           of month t
FA_t                       fa_pp_at(t, BEF_PREM)           Fixed account, start of
                                                           month t
(FA intra-month)           fa_pp_at(t, timing)             Fixed account by timing
FA_0                       fa_pp_init                      Fixed account entering month 0
S_{k,t+1}                  seg_bal_pp(t, k)                Segment in slot k, end of
                                                           month t
Sweep_t                    sweep_pp(t)                     Sweep into a new segment
S_{k,m_k}                  seg_new_pp(m)                   Segment balance at creation
(sum of segments)          seg_bal_tot_pp(t)               All live segment balances
(active pool)              seg_bal_active_pp(t)            Segments available to a draw
(pro-rata share)           seg_share(t, k)                 Segment k's share of that pool
(segment count)            seg_count(t)                    Live segments, at most 12
k                          (the ``k`` argument)            Slot, a segment's months since
                                                           creation: in month t, or at
                                                           the valuation date in the
                                                           ladder's ``_init`` cells
S_{k,0}                    seg_bal_pp_init(k)              Slot k's balance entering
                                                           month 0
(deductions to date)       seg_ded_cum_pp_init(k)          Deductions charged to slot k
(draws to date)            seg_wd_cum_pp_init(k)           Draws out of slot k
I(m_k)                     seg_index_start_init(k)         Slot k's level at creation
c_k                        seg_index_cap_init(k)           Cap declared at slot k's
                                                           creation
(start level at t)         seg_index_start(t)              Level at creation of the
                                                           segment maturing at t
(cap at t)                 seg_index_cap(t)                Cap of the segment maturing
                                                           at t
w_ix                       index_alloc_rate()              Indexed allocation share
I(t)                       index_level(t)                  Index level at monthiversary t
r_k                        index_change(i_0, i_1)          Point-to-point index change
(index path)               index_return_ann                Level annual index return
                                                           **[std]**
c                          index_cap_at(t)                 Cap in force
p                          index_par                       Participation rate
f                          index_floor                     Floor
cr_k                       index_credit_rate(r)            max(f, min(c, p x r)), engine
(the segment's cr_k)       seg_credit_rate(t)              The same, of the segment
                                                           maturing at t
(credit base)              seg_credit_base(...)            Balance the credit applies to
Credit_k                   index_credit(...)               Index credit, engine form
(matured value)            seg_matured_value(...)          Value rolling into the next
                                                           segment
(the segment's r)          seg_return(t)                   Index change of the segment
                                                           maturing at t
(credit at t)              index_credit_pp(t)              Credit added at BOM of month t
Roll^FA_t                  seg_roll_pp(t)                  Matured value rolled into FA
LCA_{t+1}                  lca_pp(t)                       Loan collateral account, end
                                                           of month t
LCA_0                      lca_pp_init                     Collateral entering month 0
Existing loan balance      loan_bal_init                   L(0), the loan entering
                                                           month 0
L_{t+1}                    loan_bal_pp(t)                  Loan plus interest, end of
                                                           month t
i_L^c                      loan_rate_ann                   Loan charged rate
i_L^e                      loan_credit_rate_ann(t)         Collateral credited rate
AV_{t+1}                   av_pp(t)                        Account value, end of month t
AV_t                       av_pp_at(t, BEF_PREM)           Account value, start of
                                                           month t
AV_0                       av_pp_init                      Account value entering month 0
(after premium)            av_pp_at(t, BEF_CREDIT)         Before the maturity credit
(after credit)             av_pp_at(t, BEF_WD)             Before the withdrawal
AV'_t                      av_pp_at(t, BEF_FEE)            After premium and withdrawal
AV'_t - MD_t               av_pp_at(t, BEF_INV)            After the monthly deduction
(aggregate AV)             av_at(t, timing)                Account value in force
(change in AV)             av_change(t)                    Change in account value
i_fix                      fixed_rate_ann(t)               Fixed-account annual rate
i_g                        guar_rate_ann                   Guaranteed annual rate
(i_fix monthly)            inv_return_mth(t)               Monthly fixed-account rate
(i_g monthly)              guar_rate_mth()                 Monthly guaranteed rate
v_g                        naar_factor()                   1 + i_gm; DB is divided by it
(interest credited)        inv_income_pp(t)                Interest on FA and LCA
e_pol                      expense_pol_mth_at(t)           Monthly policy fee
e_unit                     expense_unit_mth_at(t)          Per-unit charge per $1,000
(rider charges)            rider_charge_pp(t)              Rider charges (0)
(e_pol + e_unit + rc)      maint_fee_pp(t)                 Non-COI monthly charges
coi_t                      coi_rate(t)                     Current monthly COI rate
(guaranteed COI)           coi_rate_guar(t)                Guaranteed maximum COI rate
(guaranteed COI scale)     coi_schedule()                  The scale's number in Data
(scale's last year)        coi_rate_last_year()            The scale's last policy year
(COI by policy year)       coi_rate_guar_py(y)             The scale's rate in year y
COI_t                      coi_pp(t)                       Cost of insurance charge
NAAR_t                     net_amt_at_risk(t)              Net amount at risk
MD_t                       mth_deduction_pp(t)             Monthly deduction
MD^FA_t                    mth_deduction_from_fa_pp(t)     Deduction sourced from FA
MD^seg_{k,t}               mth_deduction_from_seg_pp(t)    Deduction sourced from
                                                           segments
(segment k's deduction)    seg_ded_pp(t, k)                Segment k's part of the
                                                           deduction
(cumulative deductions)    seg_ded_cum_pp(t, k)            Deductions charged to
                                                           segment k
DB_t                       db_pp(t)                        Death benefit after corridor
kappa_x                    corridor_factor(t)              IRC 7702(d) corridor factor
(kappa by age)             corridor_factor_at(a)           The same, keyed by age
SC_t                       surr_charge_pp(t)               Surrender charge scheduled
(SC per $1,000)            surr_charge_rate(t)             Surrender charge rate
(initial SC per $1,000)    surr_charge_rate_max()          The schedule's charge before
                                                           any run-off
(run-off period)           surr_charge_runoff_years()      The schedule's run-off, years
(AV - SC)                  csv_pp(t)                       Cash value before loan
CSV_t                      ncsv_pp(t)                      Cash surrender value, loan
                                                           netted
(SC retained)              surr_charge(t)                  Surrender charge collected
CumP_{t+1}                 cum_prem_net_pp(t)              Premiums less withdrawals and
                                                           loans, end of month t
CumP_0                     cum_prem_net_init               The same, entering month 0
(GPT/7-pay base)           cum_prem_pp(t)                  Premiums less withdrawals,
                                                           end of month t
(GPT/7-pay base at entry)  cum_prem_init                   The same, entering month 0
CumMNLP_{t+1}              cum_mnlp_pp(t)                  Cumulative no-lapse premium
                                                           through month t
(MNLP rate)                mnlp_rate()                     No-lapse premium per $1,000
                                                           p.a.
(MNLP monthly)             mnlp_pp_mth()                   Monthly no-lapse premium
(no-lapse period)          nlg_period_years()              Length of the no-lapse period
(no-lapse test)            nlg_test_ok(t)                  CumP >= CumMNLP
(NLG status)               nlg_in_effect(t)                In period and test passing
(NLG expiry shock)         nlg_expiry_shock(t)             25% shock at expiry **[std]**
(grace trigger)            is_shortfall(t)                 CSV cannot cover MD, NLG
                                                           failed
(GPT limit)                gpt_limit(t)                    max(GSP, GLP x years)
(GPT test)                 gpt_ok(t)                       GPT compliance flag
(7-pay limit)              seven_pay_limit(t)              7-pay cumulative limit
(MEC flag)                 is_mec(t)                       7-pay failure, latched
(MEC at entry)             is_mec_init                     The latch entering month 0
q^d_t                      mort_rate_mth(t)                Monthly mortality rate
(annual q)                 mort_rate(t)                    Annual mortality rate, capped
(base q by age)            mort_rate_base_at(a)            The base table's rate
(class factor)             class_factor()                  Underwriting-class multiplier
(base lapse)               lapse_rate_base(t)              Base annual lapse rate
(base lapse by year)       lapse_rate_base_py(y)           The same, keyed by policy year
(SC-expiry year)           lapse_shock_year()              Policy year of the spike
(SC-expiry spike)          lapse_rate_sc_mult(t)           Year-11 shock multiplier
r_cred,t                   cred_rate_ann(t)                Trailing credited rate
r_alt                      comp_rate_ann(t)                Competitor / market rate
(dynamic multiplier)       lapse_rate_dyn_mult(t)          Dynamic lapse multiplier
q^w_t                      lapse_rate_mth(t)               Monthly lapse rate
(annual w)                 lapse_rate(t)                   Total annual lapse rate
l_t                        pols_if(t)                      In force at BOM of month t
(l at valuation)           pols_if_init                    In force at the valuation date
(carried in)               pols_if_at(t, BEF_NB)           Carried in from month t - 1
(after new business)       pols_if_at(t, BEF_DECR)         After new business: l_t
(before maturity)          pols_if_at(t, BEF_MAT)          Before maturity: l_t
(new business)             pols_new_biz(t)                 Policies issued in month t
(deaths)                   pols_death(t)                   Deaths in month t
(lapses)                   pols_lapse(t)                   Lapses in month t
(maturities)               pols_maturity(t)                Maturities: always zero
(premium income)           premiums(t)                     Premium income
DB_t - L_t                 claims_death(t)                 Death claims
CSV_t                      claims_lapse(t)                 Surrender payments
(claims)                   claims(t)                       Death and surrender claims
W_t - fee                  withdrawals(t)                  Withdrawal payments
(inflation)                inflation_factor(t)             Expense inflation factor
E_t                        expenses(t)                     Insurer's own expenses
(premium tax)              premium_taxes(t)                Premium tax
(net loan cash flows)      net_loan_cf(t)                  Loan advances and repayments
CF_t                       net_cf(t)                       Net liability cash flow
(AV components residual)   check_av_components_resid(t)    AV less its three parts
(AV roll residual)         check_av_roll_fwd_resid(t)      AV roll-forward residual
(margin residual)          check_margin_resid(t)           Margin identity residual
(segments over the term)   check_seg_count_resid(t)        Live segments beyond 12
(the month's credit)       check_seg_credit_resid(t)       The credit, 0 or more
(least segment)            check_seg_bal_resid(t)          The least live balance
(segment closure)          check_seg_closure_resid(t)      The maturing segment's closure
(none)                     result_pols()                   Counts and decrement rates
=========================  ==============================  ==========================

Ten names needed care.

**A withdrawal is not a claim.** The notes write the withdrawal outflow as its own term
of ``CF_t``, alongside the death and surrender legs, and the library follows that: the
payment is :func:`withdrawals`, published in a ``withdrawals`` column, and
``WITHDRAWAL`` is **not** a kind :func:`claims` totals -- it would otherwise sit in the
total and be double-counted against the standalone cells.
The per-policy amount is still ``claim_pp(t, WITHDRAWAL)``, because that is
where the ``W_t - $25 fee`` rule lives and :func:`withdrawals` weights it by
:func:`pols_if`: a withdrawal is taken at BOM by policies still in force, not by a
decrement. Surrenders keep the ``LAPSE`` kind and are published as ``claims_lapse``,
so the column name matches the kind that produces it.

**The notes' month counts from issue; this model's counts from the valuation date.** The
notes' ``t`` and this model's are both 0-based and they coincide for a point issued at the
valuation date; for any other the notes' index is :func:`duration_mth`
``(t) = duration_mth_init() + t``.
Every ``mod 12`` test -- the anniversary premium, the anniversary loan -- is therefore
written against ``duration_mth(t)`` rather than ``t``, a segment's creation is a policy
month, and the surrender charge run-off uses ``duration_mth(t) + 1`` because the notes'
schedule counts the current month.

**A segment's slot is not its creation month.** ``IUL_US_S`` keys ``seg_bal_pp(t, m)``
and the segment cells beside it by ``m``, the policy month the segment was born in; this
model keys them by the slot, ``k = duration_mth(t) - m``, the months since that birth in
month ``t``, which moves with ``t``, so that ``seg_bal_pp(t, k)`` reads
``seg_bal_pp(t - 1, k - 1)``, and :func:`seg_new_pp` alone keeps the creation month. The
ladder's ``slot`` is the slot of month 0, ``duration_mth_init() - m``, which is what an
extract of a policy's live segments knows, and what one row of
``inforce_segments_sec.csv`` is keyed by.

**The notes' cash surrender value is the net one.** Their ``CSV_t`` is :func:`ncsv_pp`,
not :func:`csv_pp`: the notes define ``CSV_t = AV_t - SC_t - L_t``, with the loan already
netted. The chassis and
``CashValue_SE`` split that into :func:`csv_pp` (``AV - SC``) and :func:`ncsv_pp`
(``CSV - L``). The chassis names are kept, and the notes' symbol maps to the second.

**The withdrawal fee is inside the withdrawal, not on top of it.** These notes say
``W_t`` is "gross of $25 fee" and that the "withdrawal outflow = W_t - $25 fee". The
account is therefore debited ``W_t``, the policyholder receives ``W_t - 25`` and the
insurer keeps the fee. The universal life chassis reads its own notes the other way --
there the fee is charged *on top* of the withdrawal -- so :func:`av_pp_at` deliberately
differs from the chassis at ``BEF_FEE``. A planned withdrawal above 0 and below the fee
would debit the account less than the fee it is charged, which :func:`proj_len` refuses.

**The death claim nets the loan at the end of the month.** These notes write
``death claim outflow = DB_t - L_t``; decrements are end-of-month events, after the
loan has accrued, so :func:`claim_pp` uses :func:`loan_bal_pp` at ``t``. The chassis
uses the opening balance because its own notes write ``L(t-1)``.

**The maintenance fee is income, the expenses outgo.** As on the chassis,
:func:`maint_fee_pp` is the non-COI part of the monthly deduction -- a charge *against
the account value* -- while :func:`expenses` is the insurer's own $75 a year plus $150
at issue **[std]**. Confusing them double-counts.

**The two cumulative premium accumulators are different.** :func:`cum_prem_net_pp` is
the notes' ``CumP_t``, premiums less withdrawals **and loans**, which is what the
no-lapse test compares against ``CumMNLP_t``. :func:`cum_prem_pp` is premiums less
withdrawals only, which is the base of the guideline premium and 7-pay tests. Using one
for the other quietly changes both answers, and so does opening either at 0 on a point in
force: each opens from a column of its own, :func:`cum_prem_init` and
:func:`cum_prem_net_init`.

**The MEC flag latches here, and does not in the S model.** ``IUL_US_S``'s flag is the
in-year 7-pay test alone, which stops applying in policy year 8 and so switches the flag
off exactly when the failure becomes permanent. This model latches it, as ``UL_US_S``
does, from :func:`is_mec_init` on a point in force: under IRC 7702A a contract that fails
the test is a modified endowment contract for good [R5].

**The fixed account and the collateral are not the account value less the loan.**
``IUL_US_S`` opens an in-force point with everything in the fixed account and the
collateral equal to the loan. Both part from those after the first loan: the collateral
is credited at :func:`loan_credit_rate_ann` while the loan accrues at ``loan_rate_ann``,
and the segments hold the rest of the account value. So each opens from its own column,
:func:`fa_pp_init` and :func:`lca_pp_init`, and the segments from the ladder; ``Data``
holds the account value to the sum of the three parts.

.. rubric:: Codes

What :mod:`~.IUL_US_S` spells as text, a timing, a kind, the basis or the credit base's
convention, is here an int Reference named as the text it replaces, so that every cell
takes and returns C numbers. A call site reads as it did, less the quotes:
``pols_if_at(t, BEF_DECR)``, ``av_pp_at(t, BEF_FEE)``, ``claim_pp(t, DEATH)``,
``basis = GUARANTEED``.

=============  =====  ===============================================================
Reference      Value  Meaning
=============  =====  ===============================================================
BEF_NB         0      :func:`pols_if_at`: the count carried in from month t - 1
BEF_DECR       1      :func:`pols_if_at`: that count plus month t's new business
BEF_MAT        2      :func:`pols_if_at`: before any maturity, the BEF_DECR count
BEF_PREM       3      the accounts: the value carried in, before the premium
BEF_CREDIT     4      :func:`fa_pp_at`, :func:`av_pp_at`, :func:`av_at`: after the net
                      premium, before the maturing segment's credit
BEF_WD         5      :func:`fa_pp_at`, :func:`av_pp_at`, :func:`av_at`: after the
                      credit, before the withdrawal and the loan
BEF_FEE        6      :func:`fa_pp_at`, :func:`av_pp_at`, :func:`av_at`: after the
                      draws, before the monthly deduction
BEF_SWEEP      7      :func:`fa_pp_at`: after the deduction, before the sweep
BEF_INV        8      the accounts: after the deduction and the sweep, before interest
EOM            9      :func:`av_at`: after interest, before decrements
DEATH          0      :func:`claim_pp`, :func:`claims_from_av`: the death claim
LAPSE          1      :func:`claim_pp`, :func:`claims_from_av`: the surrender claim
MATURITY       2      :func:`claims_from_av`: none, the contract never matures
WITHDRAWAL     3      :func:`claim_pp`: the withdrawal, which is no claim
CURRENT        0      ``basis``: the current, non-guaranteed scales
GUARANTEED     1      ``basis``: the contractual guarantees alone
REMAINING      0      ``seg_credit_base_conv``: the credit on the remaining balance
ADJ_BEGIN      1      ``seg_credit_base_conv``: the adjusted beginning value, deductions
                      half-weighted
=============  =====  ===============================================================

The accounts are :func:`fa_pp_at`, which takes the six timings from ``BEF_PREM`` to
``BEF_INV``; :func:`av_pp_at`, which takes those but ``BEF_SWEEP``, since a sweep moves
value between the account value's parts and changes no total; :func:`lca_pp_at`, which
moves only at the loan, ``BEF_PREM`` and ``BEF_INV``; and :func:`av_at`, the account value
in force, which takes :func:`av_pp_at`'s five and ``EOM``.

The model has two families of timing, the count's and the accounts', passed to different
cells, and they are numbered as one: ``BEF_NB`` 0 and ``BEF_DECR`` 1, as in every SEC
model, then the count's third, ``BEF_MAT``, then the accounts' in the order of their
instants within the month, ``EOM`` last, as ``UL_US_SEC`` numbers its own with the two
instants an indexed account adds, ``BEF_CREDIT`` and ``BEF_SWEEP``, in their places. So no
two timings share a code, and a code of one family passed to the other's cell,
``av_pp_at(t, BEF_NB)``, is refused as any timing the cell does not take is,
``ValueError("invalid timing")``, in both engines, rather than read as a timing of the
cell's own. Kinds are numbered in the order the month settles them, as ``VUL_US_SEC``
numbers its own. ``basis`` and ``seg_credit_base_conv``, the two text References
``IUL_US_S`` switches on, are code families of their own, each holding one of its codes,
``CURRENT`` and ``REMAINING`` as shipped: a run on the guaranteed basis sets
``basis = GUARANTEED`` before anything computes, and in modelx a string set on either
meets its cell's own refusal, ``"invalid basis"`` or ``"invalid credit base"``. A cell
compares its code with ``==`` alone, never by order or by membership of a tuple, so that
a text passed where a code is taken meets the cell's own refusal in modelx too. A timing
or a kind indexes its cell's cache, a C array of twelve codes a month, since every 2-D
cache of the model has one width, the twelve slots of a segment's life
(``spec_sec.py``), so codes are numbered densely from 0. They are References, not cells,
so the symbol map does not list them. Every other Reference is named in lower case,
``issue_age_min`` and ``issue_age_max`` among them, the contract's issue ages, which
:func:`proj_len` refuses a point outside of, and the first of which the compiled model's
caches are sized from.

.. rubric:: Reporting cells

:func:`model_point`, the label accessors :func:`sex`, :func:`rate_class`,
:func:`db_option`, :func:`qual_test`, :func:`premium_type`, :func:`premium_mode` and
:func:`surr_charge_id`, the reports :func:`result_cf`, :func:`result_pols`,
:func:`result_av` and :func:`result_seg`, and the checks :func:`check_av_components`,
:func:`check_av_roll_fwd`, :func:`check_seg_ladder` and :func:`check_margin` are written
for a reader and for the comparison with :mod:`~.IUL_US_S`, which has every one of them: a
table row, text, DataFrames and four verdicts. No other cell calls them: each reads the
number ``Data`` decoded from the same column instead, the decodes' flags, the schedule
numbers and the joins the keys select. So the row, the text and the frames stay Python
when the model compiles. A label accessor returns its column as read, text or not: a
blank ``surr_charge_id`` on a point without a charge reads as NaN, and the compiled
accessor returns the same. Every other cell returns a C ``bint``, ``long long`` or
``double``, and so do the four checks, which may stay Python but compile to a ``bint``,
their verdict, as their per-month residuals, ``*_resid``, compile to a ``double``.

The crediting engine of ``IUL_US_S``, :func:`index_change`, :func:`index_credit_rate`,
:func:`seg_credit_base`, :func:`index_credit` and :func:`seg_matured_value`, cells of
float arguments, is kept as it is, for its worked example, which prices one segment's
credit at the current and the guaranteed cap through it, and for the comparison with
:mod:`~.IUL_US_S`, whose projection calls it. No projection cell here calls it: the credit
of the segment maturing in month ``t`` is :func:`seg_return`, :func:`seg_credit_rate` and
:func:`index_credit_pp`, cells keyed by the month, which compute what the engine computes
in its order. Compiled, the five keep a Python dict for a cache and Python objects for
their defaulted parameters, as the registry admits them (R14).
"""

from modelx.serialize.jsonvalues import *

_formula = lambda idx: None

_bases = []

_allow_none = None

_spaces = []

# ---------------------------------------------------------------------------
# Cells

[docs] def model_point(): """The selected model point, its row of *model_point_table_sec.csv*, as a Series. Row ``idx`` of the table, for a reader who wants every column at once: a reporting cell (the Space docstring's *Reporting cells*), which no projection cell reads. Each reads its own ``Data`` vector instead. """ return data.model_point_table().iloc[idx] # noqa: F821
[docs] def point_id(): """The label of the selected model point, its ``point_id``, from ``Data.point_id``. ``Projection`` is indexed by position, ``idx``, as ``basiclife.BasicTerm_SC`` is; the label is what a reader finds in the table, so every refusal names it. """ return int(data.point_id()[idx]) # noqa: F821
[docs] def age_at_entry(): """The issue age (ANB) of the selected model point, from ``Data.age_at_entry``. The age at issue, whatever the policy's duration at the valuation date; the attained age in month t is :func:`age`. ``Data`` holds it to a whole number, 0 or more, and :func:`proj_len` to the ages the contract issues, 0 to 85. """ return int(data.age_at_entry()[idx]) # noqa: F821
[docs] def sex(): """The sex of the selected model point. A reporting cell (the Space docstring): ``Data`` joins the COI scale by it, through ``Data.coi_schedule``, and no projection cell reads it here. Returned as read. """ return model_point()["sex"]
[docs] def rate_class(): """The underwriting class of the selected model point (spec Table 1) [S3]. A reporting cell (the Space docstring): ``Data`` joins the COI scale and the class factor by it, through ``Data.coi_schedule`` and ``Data.class_factor``, and no projection cell reads it here. Returned as read. """ return model_point()["rate_class"]
[docs] def sum_assured(): """F: the initial face amount of the selected model point, the face at issue. The surrender charge is quoted per $1,000 of this, the *initial* face, not of :func:`sum_assured_at` [S3], and it is the face a point not yet in force is issued with. The face in force at the valuation date is :func:`sum_assured_init`, and the face in force in month t is :func:`sum_assured_at`. """ return float(data.sum_assured()[idx]) # noqa: F821
[docs] def db_option(): """The death benefit option: ``"A"`` (level) or ``"B"`` (face plus account value). The Graded and Return of Premium options are minority designs excluded from the baseline by the product spec (F3). A reporting cell (the Space docstring): the projection reads :func:`is_db_option_a` and :func:`is_db_option_b`, ``Data``'s decodes of the column. Returned as read. """ return model_point()["db_option"]
[docs] def is_db_option_a(): """Whether the death benefit is Option A, the level face. ``Data.is_db_option_a`` at the point: ``db_option`` is ``"A"``, the decode of the model point's column ``Data`` makes once for the table, compared exactly, as ``IUL_US_S`` compares it, so that no monthly cell branches on text; :func:`db_pp` and :func:`face_reduction_pp` read this instead. The label accessor :func:`db_option` is kept as it is, for reporting, and no projection cell calls it. """ return bool(data.is_db_option_a()[idx]) # noqa: F821
[docs] def is_db_option_b(): """Whether the death benefit is Option B, the face plus the account value. ``Data.is_db_option_b`` at the point: ``db_option`` is ``"B"``, read by :func:`db_pp`, which raises on a point that is neither A nor B, as ``IUL_US_S``'s does. """ return bool(data.is_db_option_b()[idx]) # noqa: F821
[docs] def qual_test(): """The IRC 7702 qualification test elected at issue; only ``"GPT"`` is modeled. GPT is the baseline (spec F4) because the Overloan Protection Rider attaches only to GPT non-MEC policies [S3]; CVAT is documented as a variation, so :func:`corridor_factor` raises on anything else rather than silently applying GPT corridor factors. A reporting cell (the Space docstring): the projection reads :func:`is_gpt`, ``Data``'s decode of the column. Returned as read. """ return model_point()["qual_test"]
[docs] def is_gpt(): """Whether the point elected the Guideline Premium Test: ``qual_test`` is ``"GPT"``. ``Data.is_gpt`` at the point, the decode of the model point's ``qual_test`` column, read by :func:`corridor_factor`, which raises on any other test, as ``IUL_US_S``'s does: CVAT is documented as a variation, out of the baseline. """ return bool(data.is_gpt()[idx]) # noqa: F821
[docs] def premium_type(): """The premium pattern: ``"LEVEL"``, ``"SINGLE"`` or ``"TARGET"`` **[std]**. A reporting cell (the Space docstring): the projection reads :func:`is_level_premium`, :func:`is_single_premium` and :func:`is_target_premium`, ``Data``'s decodes of the column. Returned as read. """ return model_point()["premium_type"]
[docs] def is_level_premium(): """Whether the premium pattern is LEVEL: ``premium_type`` is ``"LEVEL"``. ``Data.is_level_premium`` at the point: one of the three decodes of the model point's ``premium_type`` column that :func:`premium_pp` branches on, each made once for the table by ``Data``, so that no monthly cell compares text; :func:`premium_pp` raises on a point that is none of the three, as ``IUL_US_S``'s does. The label accessor :func:`premium_type` is kept as it is, for reporting, and no projection cell calls it. """ return bool(data.is_level_premium()[idx]) # noqa: F821
[docs] def is_single_premium(): """Whether the premium pattern is SINGLE: ``premium_type`` is ``"SINGLE"``. ``Data.is_single_premium`` at the point, a decode of the model point's ``premium_type`` column, read by :func:`premium_pp`. """ return bool(data.is_single_premium()[idx]) # noqa: F821
[docs] def is_target_premium(): """Whether the premium pattern is TARGET: ``premium_type`` is ``"TARGET"``. ``Data.is_target_premium`` at the point, a decode of the model point's ``premium_type`` column, read by :func:`premium_pp`, whose TARGET premium is capped inside the guideline premium limit. """ return bool(data.is_target_premium()[idx]) # noqa: F821
[docs] def premium_mode(): """The premium mode: ``"ANNUAL"`` **[std]** baseline, or ``"MONTHLY"``. The notes fix the baseline at annual premiums paid at BOM of the first month of each policy year (``duration_mth(t) % 12 == 0``) **[std]**; monthly mode is carried so the chassis' level-pay pattern remains reachable. A reporting cell (the Space docstring): the projection reads :func:`is_annual_premium` and :func:`is_monthly_premium`, ``Data``'s decodes of the column. Returned as read. """ return model_point()["premium_mode"]
[docs] def is_annual_premium(): """Whether premiums are paid annually: ``premium_mode`` is ``"ANNUAL"``. ``Data.is_annual_premium`` at the point: one of the two decodes of the model point's ``premium_mode`` column that :func:`premium_pp` branches on, made once for the table by ``Data``, so that no monthly cell compares text; :func:`premium_pp` raises on a point that is neither, as ``IUL_US_S``'s does. The label accessor :func:`premium_mode` is kept as it is, for reporting, and no projection cell calls it. """ return bool(data.is_annual_premium()[idx]) # noqa: F821
[docs] def is_monthly_premium(): """Whether premiums are paid monthly: ``premium_mode`` is ``"MONTHLY"``. ``Data.is_monthly_premium`` at the point, a decode of the model point's ``premium_mode`` column, read by :func:`premium_pp`. """ return bool(data.is_monthly_premium()[idx]) # noqa: F821
[docs] def premium_pp_ann(): """The planned annual premium per policy; a billing target only, premiums flexible.""" return float(data.premium_pp_ann()[idx]) # noqa: F821
[docs] def index_alloc_rate(): """w_ix: the share of the sweepable fixed-account balance moved to the indexed account. 100% in the baseline **[std]**. A model point at 0% never creates a segment and accumulates entirely at the fixed-account rate, which is the control run for the segment ladder. """ return float(data.index_alloc_rate()[idx]) # noqa: F821
[docs] def av_pp_init(): """AV(0): the account value per policy entering month 0, the valuation month. The ``av_pp_init`` column, ``IUL_US_S``'s own: the balance at the close of policy month ``duration_mth_init() - 1``, before any month-0 event, which is what ``IUL_US_S`` carries into the month as ``av_pp_at(d, BEF_PREM)`` at ``d = duration_mth_init()``. It opens the account value chain at :func:`t_entry` on a point issued at or after the valuation date, 0 there. A point in force opens the chain from its parts instead, which ``Data`` holds this column to, so that an extract whose amounts are carried to the cent opens one account (see :func:`av_pp_at`). Zero for a point not yet in force, which is issued with no account value. The account value is the fixed account, the live segments and the loan collateral, and each of the three opens from a value of its own -- :func:`fa_pp_init`, the segment ladder and :func:`lca_pp_init` -- where ``IUL_US_S`` places the whole opening balance less the loan in the fixed account and starts with no live segment. ``Data`` holds this column to their sum, to the cent. It may be negative: ``IUL_US_S`` lapses no policy for insufficiency, and charges an exhausted policy on, so its point 5's account value closes below zero from policy month 604, and a point restated after that month carries that balance (see the model docstring). """ return float(data.av_pp_init()[idx]) # noqa: F821
[docs] def loan_bal_init(): """L(0): the policy loan balance per policy entering month 0. The ``loan_bal_init`` column, ``IUL_US_S``'s own: the debt at the close of policy month ``duration_mth_init() - 1``, interest accrued to then included, before any month-0 event; the opening balance of :func:`loan_bal_pp` at :func:`t_entry`, and the loan month 0's shortfall test nets. Zero for a point not yet in force. ``IUL_US_S`` also opens its loan collateral account from it, taking the collateral equal to the debt; here the collateral opens from a column of its own, :func:`lca_pp_init`, since the two part once interest accrues. """ return float(data.loan_bal_init()[idx]) # noqa: F821
[docs] def fa_pp_init(): """FA(0): the fixed (holding) account per policy entering month 0. The ``fa_pp_init`` column: the fixed account at the close of policy month ``duration_mth_init() - 1``, before any month-0 event, which is what ``IUL_US_S`` carries into the month as ``fa_pp_at(d, BEF_PREM)``. It is the opening balance of :func:`fa_pp_at` at :func:`t_entry`. ``IUL_US_S`` opens its in-force points with the account value less the loan here, everything outside the collateral in the fixed account and no live segment, which re-opening a policy restates wrongly: the segments hold most of an account value whose allocation is indexed, and the collateral is not the loan once interest accrues. It may be negative. ``IUL_US_S`` lapses no policy for insufficiency, and its fixed account carries every deduction and draw the segments cannot cover, so an exhausted policy's fixed account runs below zero: its point 5's closes below zero from policy month 383. ``Data`` holds it, with the collateral and the segments, to :func:`av_pp_init`. Zero for a point not yet in force. """ return float(data.fa_pp_init()[idx]) # noqa: F821
[docs] def lca_pp_init(): """LCA(0): the loan collateral account per policy entering month 0. The ``lca_pp_init`` column: the collateral at the close of policy month ``duration_mth_init() - 1``, before any month-0 event, which is what ``IUL_US_S`` carries into the month as ``lca_pp_at(d, BEF_PREM)``. It is the opening balance of :func:`lca_pp_at` at :func:`t_entry`, and part of the account value, as the debt is not. A standard loan moves value out of the fixed account and the segments into the collateral, so the two coincide on the loan's first day, and ``IUL_US_S`` takes them equal at the start of its frame **[std]**; after that the collateral grows at the rate credited, :func:`loan_credit_rate_mth`, and the debt at the rate charged, :func:`loan_rate_mth`, so they part. ``Data`` refuses a collateral without a loan, or a loan without one. Zero for a point not yet in force. """ return float(data.lca_pp_init()[idx]) # noqa: F821
[docs] def sum_assured_init(): """F(0): the face amount in force per policy entering month 0. The ``sum_assured_init`` column: the face in force at the close of policy month ``duration_mth_init() - 1``, after every Option A withdrawal cut to date, which is the face ``IUL_US_S`` carries into the month as ``sum_assured_at(d - 1)``. It is the base of :func:`sum_assured_at` at :func:`t_entry`, so month 0's own withdrawal cut, death benefit, net amount at risk and per-unit charge are measured from it. The face at issue, :func:`sum_assured`, stays the surrender charge's base, and ``Data`` refuses a value above it, since face increases are not modelled. It may be 0: withdrawals under Option A can cut the face to nothing while the policy stays in force, as ``IUL_US_S`` carries it. Zero for a point not yet in force, which is issued at :func:`sum_assured`. ``IUL_US_S`` opens its in-force points at the face at issue. """ return float(data.sum_assured_init()[idx]) # noqa: F821
[docs] def cum_prem_init(): """CumPrem(0): the premiums less withdrawals per policy before the valuation date. The ``cum_prem_init`` column: every gross premium :func:`premium_pp` collected from issue through policy month ``duration_mth_init() - 1``, less every withdrawal :func:`wd_pp` paid, which is what ``IUL_US_S`` carries into the month as ``cum_prem_pp(d - 1)``. :func:`cum_prem_pp` opens from it at :func:`t_entry`, so the GPT test, the 7-pay test and the TARGET premium cap of month 0 all count the premiums paid before the valuation date. ``IUL_US_S`` opens its accumulator at 0 on any point, the notes giving no opening accumulator **[std]**, so its flags are meaningful only for points projected from issue. It may be negative. The statutory "less a portion of withdrawals" is taken as the whole withdrawal **[std]**, so this is a tax measure, not a balance, and withdrawals can exceed the premiums paid. Zero for a point not yet in force. """ return float(data.cum_prem_init()[idx]) # noqa: F821
[docs] def cum_prem_net_init(): """CumP(0): premiums less withdrawals and loans per policy before the valuation date. The ``cum_prem_net_init`` column, the no-lapse guarantee's accumulator: every gross premium collected from issue through policy month ``duration_mth_init() - 1``, less every withdrawal and every new loan, which is what ``IUL_US_S`` carries into the month as ``cum_prem_net_pp(d - 1)``. :func:`cum_prem_net_pp` opens from it at :func:`t_entry`, so the no-lapse test of month 0 compares every premium since issue with the cumulative minimum no-lapse premium since issue, which :func:`cum_mnlp_pp` counts on the policy clock. Opened at 0, as ``IUL_US_S`` opens it, a policy in force would fail that test at once and lose its guarantee. It may be negative, as loans can exceed the premiums paid net of withdrawals; ``Data`` holds it to at most :func:`cum_prem_init`, to a cent and a half, since loans only lower it. Zero for a point not yet in force. """ return float(data.cum_prem_net_init()[idx]) # noqa: F821
[docs] def is_mec_init(): """The MEC latch entering month 0: whether the 7-pay test failed before it. The ``is_mec_init`` column, an int code: 1 for a policy that failed the 7-pay test in some month before the valuation date, and so is a modified endowment contract for good, 0 otherwise. :func:`is_mec` latches on it at :func:`t_entry`, so a policy that failed in its first seven years stays a MEC after them, where the in-year test no longer applies. ``IUL_US_S``'s flag does not latch, so the generator reads whether its in-year test failed in any month before ``duration_mth_init()``. ``Data`` refuses a 0 where ``cum_prem_init`` already exceeds the 7-pay limit of the month before the valuation date, inside the first seven policy years. Read as a bool, so 1.0 reads as True. Zero for a point not yet in force. """ return bool(data.is_mec_init()[idx]) # noqa: F821
[docs] def seg_bal_pp_init(k): """S_k(0): the balance per policy entering month 0 of the segment in ladder slot k. ``Data.seg_bal_pp_init`` at this point and slot ``k``, the ``seg_bal_pp_init`` column of ``inforce_segments_sec.csv``: ``k`` is the months since the segment's creation at the valuation date, and the value is the balance at the close of policy month ``duration_mth_init() - 1`` of the segment born in policy month ``duration_mth_init() - k``, which is what ``IUL_US_S`` carries into the month as ``seg_bal_pp(d - 1, d - k)``. :func:`seg_bal_pp` opens each live segment from it at :func:`t_entry`, its slot then the ladder's, :func:`seg_bal_active_pp` sums slots 1 to 11 into month 0's pool, and slot 12, the segment maturing at ``t = 0``, is what month 0's maturity rolls into the fixed account (:func:`seg_roll_pp`). ``Data`` holds it to ``-1e-8`` or more, the tolerance :func:`check_seg_ladder` holds a live balance to, and :func:`proj_len` refuses a point whose ladder does not hold exactly slots 1 to ``min(12, duration_mth_init())``. Read only on a point in force, at ``1 <= k <= 12``. Like the other four readers of the ladder, it asks :func:`proj_len` first, so that a ladder missing a slot is refused by name before any value of it is read, and then refuses a slot below 1 or past the point's last, naming the point and the slot, where stage ``E``'s ``.loc`` raised pandas' ``KeyError``, so that no read meets ``Data``'s padding. """ proj_len() if k < 1 or k > data.inforce_segment_last()[idx]: # noqa: F821 raise ValueError(f"point_id {point_id()}: inforce_segments_sec.csv holds no " f"segment in slot {k}") return float(data.seg_bal_pp_init()[idx, k]) # noqa: F821
[docs] def seg_ded_cum_pp_init(k): """The deductions per policy charged to the segment in ladder slot k before month 0. ``Data.seg_ded_cum_pp_init`` at the point and slot ``k``, the ``seg_ded_cum_pp_init`` column of ``inforce_segments_sec.csv``: every monthly deduction the segment born in policy month ``duration_mth_init() - k`` has borne since its creation, through the close of policy month ``duration_mth_init() - 1``, which is ``IUL_US_S``'s ``seg_ded_cum_pp(d - 1, d - k)``. With the balance and the draws it is the segment's credit base: :func:`seg_ded_cum_pp` opens from it at :func:`t_entry`, and in slot 12 :func:`index_credit_pp` reads it at ``t = 0``, where the credit base convention ``ADJ_BEGIN`` half-weights it. Read only on a point in force, at ``1 <= k <= 12``, after :func:`proj_len`, and refused, as :func:`seg_bal_pp_init` refuses it, at a slot the point does not hold. """ proj_len() if k < 1 or k > data.inforce_segment_last()[idx]: # noqa: F821 raise ValueError(f"point_id {point_id()}: inforce_segments_sec.csv holds no " f"segment in slot {k}") return float(data.seg_ded_cum_pp_init()[idx, k]) # noqa: F821
[docs] def seg_wd_cum_pp_init(k): """The draws per policy out of the segment in ladder slot k before month 0. ``Data.seg_wd_cum_pp_init`` at the point and slot ``k``, the ``seg_wd_cum_pp_init`` column of ``inforce_segments_sec.csv``: every withdrawal and loan transfer the segment born in policy month ``duration_mth_init() - k`` has paid since its creation, through the close of policy month ``duration_mth_init() - 1``, which is ``IUL_US_S``'s ``seg_wd_cum_pp(d - 1, d - k)``. :func:`seg_wd_cum_pp` opens from it at :func:`t_entry`, and in slot 12 :func:`index_credit_pp` reads it at ``t = 0``. Read only on a point in force, at ``1 <= k <= 12``, after :func:`proj_len`, and refused, as :func:`seg_bal_pp_init` refuses it, at a slot the point does not hold. """ proj_len() if k < 1 or k > data.inforce_segment_last()[idx]: # noqa: F821 raise ValueError(f"point_id {point_id()}: inforce_segments_sec.csv holds no " f"segment in slot {k}") return float(data.seg_wd_cum_pp_init()[idx, k]) # noqa: F821
[docs] def seg_index_start_init(k): """I(m_k): the index level at the creation of the segment in ladder slot k. ``Data.seg_index_start_init`` at the point and slot ``k``, the ``seg_index_start_init`` column of ``inforce_segments_sec.csv``: the index level the segment born in policy month ``duration_mth_init() - k`` started from, on this model's path, the valuation clock's, whose level at the valuation date is ``index_level_init``: ``IUL_US_S``'s level at the segment's creation month times ``index_level_init`` over its level at month ``duration_mth_init()``. So the segment's return at maturity, a ratio of two levels, is ``IUL_US_S``'s. Read for the segment maturing in month ``t < 12`` by :func:`seg_index_start`, and only on a point in force, at ``1 <= k <= 12``, after :func:`proj_len`; ``Data`` holds it above 0, since the return divides by it, and it is refused, as :func:`seg_bal_pp_init` refuses it, at a slot the point does not hold. """ proj_len() if k < 1 or k > data.inforce_segment_last()[idx]: # noqa: F821 raise ValueError(f"point_id {point_id()}: inforce_segments_sec.csv holds no " f"segment in slot {k}") return float(data.seg_index_start_init()[idx, k]) # noqa: F821
[docs] def seg_index_cap_init(k): """c_k: the cap declared at the creation of the segment in ladder slot k. ``Data.seg_index_cap_init`` at the point and slot ``k``, the ``seg_index_cap_init`` column of ``inforce_segments_sec.csv``: the cap in force when the segment born in policy month ``duration_mth_init() - k`` was created, which its credit at maturity is capped at, the cap being re-declared at every segment start [S3][S4]. ``IUL_US_S`` holds the cap level, so every segment carries :func:`index_cap_at`'s value; the column lets a cap re-declared at the valuation date apply to new segments only. Read for the segment maturing in month ``t < 12`` by :func:`seg_index_cap`, and only on a point in force, at ``1 <= k <= 12``, after :func:`proj_len`; ``Data`` holds it to 0 or more, and it is refused, as :func:`seg_bal_pp_init` refuses it, at a slot the point does not hold. """ proj_len() if k < 1 or k > data.inforce_segment_last()[idx]: # noqa: F821 raise ValueError(f"point_id {point_id()}: inforce_segments_sec.csv holds no " f"segment in slot {k}") return float(data.seg_index_cap_init()[idx, k]) # noqa: F821
[docs] def policy_count(): """The number of policies the model point stands for, its ``policy_count`` column. A point in force at the valuation date counts the policies in force then, before any month-0 event; any other point counts the policies it issues. Either way the count enters the projection once: as :func:`pols_if_init` for the first, as :func:`pols_new_biz` in the issue month for the second. Every per-policy value -- the accounts, the segments, the loan, the face, the opening state -- is the same whatever the count, and every cash flow is a per-policy amount weighted by it. """ return float(data.policy_count()[idx]) # noqa: F821
[docs] def pols_if_init(): """Policies in force at the valuation date, before any month-0 event. ``policy_count()`` for a point already in force at ``t = 0`` (``duration_mth_init() > 0``), and 0 for one issued at or after it, whose policies enter through :func:`pols_new_biz` in the issue month instead, as in ``basiclife.BasicTerm_SE``. So on a point issued at ``t = 0`` this is 0, and ``pols_if(0)`` is the issued count. ``IUL_US_S``'s cell of the name is the notes' ``l(0)``, the count at the start of its frame, which on new business is the issued count. """ return policy_count() if duration_mth_init() > 0 else 0.0
[docs] def duration_mth_init(): """Completed policy months at the valuation date, the ``duration_mth`` column. The policy's age in months at ``t = 0``: 60 for point 6 and 888 for point 11, ``IUL_US_S``'s point 1 on its fifth anniversary and two years before the end of its projection, 0 for a policy issued at the valuation date, and -25 for point 12, to be issued 25 months after it, which ``Data`` admits up to ``future_horizon_mth`` months ahead. This is the notes' issue-date / duration offset attribute, an elapsed count and therefore already 0-based, and ``IUL_US_S``'s cell and column of the same name, which count from the first month of its own frame; here that month is the valuation date for every point, and the count may be negative. It is the one fact the policy clock takes from the model point. """ return int(data.duration_mth()[idx]) # noqa: F821
[docs] def has_surr_charge(): """Whether a surrender charge schedule applies to this model point. ``Data.has_surr_charge`` at the point: its ``has_surr_charge`` column, which ``Data`` holds to True or False in any case. """ return bool(data.has_surr_charge()[idx]) # noqa: F821
[docs] def surr_charge_id(): """The surrender charge schedule ID, a row label of *surr_charge_table.csv*. A reporting cell (the Space docstring): ``Data`` joins the schedule by it, through ``Data.surr_charge_rate_max`` and ``Data.surr_charge_runoff_years``, and no projection cell reads it here. Returned as read: a blank id on a point without a charge is NaN. """ return model_point()["surr_charge_id"]
[docs] def surr_charge_rate_max(): """The schedule's charge per $1,000 of initial face, before any of it runs off. ``Data.surr_charge_rate_max`` at the point: the ``sc_per_1000_init`` column of the point's row of *surr_charge_table.csv*, $25.00 on the shipped ``IUL10`` schedule; :func:`surr_charge_rate` runs it off from here. ``Data`` joins the schedule to the points by ``surr_charge_id`` once it has checked the table, so that no projection cell reads the table or the id, and refuses the table, naming every point, where a point that :func:`has_surr_charge` names an id the table lacks, which ``IUL_US_S``'s ``.loc`` met in every month of its cover. :func:`surr_charge_rate` reads it only where :func:`has_surr_charge` is true, but a point without a charge reads its schedule too, as at stage ``E``, where the table holds its id; where it does not, ``Data.has_surr_charge_schedule`` is 0, and this raises ``ValueError``, naming the point, where stage ``E``'s refused it. """ value = float(data.surr_charge_rate_max()[idx]) # noqa: F821 if not data.has_surr_charge_schedule()[idx]: # noqa: F821 raise ValueError(f"point_id {point_id()}: surr_charge_table.csv has no row for " f"its surr_charge_id") return value
[docs] def surr_charge_runoff_years(): """The number of policy years over which the schedule's charge runs off, linearly. ``Data.surr_charge_runoff_years`` at the point: the ``runoff_years`` column of the point's row of *surr_charge_table.csv*, 10 on the shipped ``IUL10`` schedule, read as a float, as ``IUL_US_S`` reads it, and joined, checked and refused as :func:`surr_charge_rate_max` is. ``Data`` holds it to a whole number of years, 1 or more, so that the division in :func:`surr_charge_rate` never meets 0 and :func:`lapse_shock_year`'s ``int()`` of it changes nothing, and to below ``2**53`` years on a point with a charge, where that ``int()`` is exact. """ value = float(data.surr_charge_runoff_years()[idx]) # noqa: F821 if not data.has_surr_charge_schedule()[idx]: # noqa: F821 raise ValueError(f"point_id {point_id()}: surr_charge_table.csv has no row for " f"its surr_charge_id") return value
[docs] def wd_first_year(): """The first policy year in which a withdrawal may be taken. 2 in the shipped points: withdrawals are allowed after the free-look period [S3] and the model takes that as the first anniversary **[std]**. """ return int(data.wd_first_year()[idx]) # noqa: F821
[docs] def wd_pp_mth(): """The planned partial withdrawal per policy, in each month withdrawals are allowed. The model point's ``wd_pp`` column, a monthly amount, gross of the $25 fee and **0 in the baseline** [std]; model point 5 takes $200 a month. Read once a point here, so that :func:`wd_pp`, a monthly cell on the accounts' chains, reads no model point column in its own formula. ``Data`` holds it to 0 or more, and :func:`proj_len` refuses one above 0 and below the fee. """ return float(data.wd_pp()[idx]) # noqa: F821
[docs] def loan_first_year(): """The first policy year in which the distribution-scenario loan is drawn. The notes' loan utilization module borrows a level amount annually from a start age, e.g. 65 **[std]**; 21 for issue age 45 is that age expressed as a policy year. """ return int(data.loan_first_year()[idx]) # noqa: F821
[docs] def loan_new_pp_ann(): """The planned standard loan per policy, drawn at each anniversary loans are taken. The model point's ``loan_new_pp_ann`` column, **0 in the baseline** -- the notes set loan utilization to none -- and $6,000 a year on model point 5. Read once a point here, so that :func:`loan_new_pp`, a monthly cell on the accounts' and the loan's chains, reads no model point column in its own formula. ``Data`` holds it to 0 or more. """ return float(data.loan_new_pp_ann()[idx]) # noqa: F821
[docs] def mnlp_rate(): """The minimum monthly no-lapse premium rate per $1,000 of face, annualized [S3]. 20.80 for M / Non-Tobacco / 45 / band 1 [S3]: the entry in one carrier's base annual minimum premium rate table for faces of $25,000-$99,999, which that carrier does not label as MNLP rates, so reading it as the annualized MNLP is **[std]**. The 250,000 example face falls in the same carrier's $100,000-and-up table, which gives 11.32 for the same cell [S3]; the band-1 rate stands in **[std]**. """ return float(data.mnlp_rate()[idx]) # noqa: F821
[docs] def gsp(): """The guideline single premium (GPT compliance input) **[std]** placeholder. No retrieved source gives guideline premiums for this composite, so the shipped value is a plausible placeholder, not a computed IRC 7702 figure. """ return float(data.gsp()[idx]) # noqa: F821
[docs] def glp(): """The guideline level premium (GPT compliance input) **[std]** placeholder.""" return float(data.glp()[idx]) # noqa: F821
[docs] def seven_pay_prem(): """The 7-pay premium (IRC 7702A compliance input) **[std]** placeholder [R5].""" return float(data.seven_pay_prem()[idx]) # noqa: F821
[docs] def duration_mth(t): """Completed policy months at the beginning of month t, the **policy** clock. ``duration_mth_init() + t``: ``t`` counts months from the valuation date and ``duration_mth(t)`` months from issue, and the two move together. A closed form, where ``basiclife.BasicTerm_SE`` adds one a month by recursion: the same numbers, without a call chain as long as the frame. It is the notes' own month index, 0 in the issue month -- ``t = 0`` for a point issued at the valuation date -- and negative before issue. Anniversary events test ``duration_mth(t) % 12 == 0``, and a segment's creation month, the ``m`` of :func:`seg_new_pp`, is a value of it, its slot in month ``t``, the ``k`` of :func:`seg_bal_pp`, ``duration_mth(t) - m``. """ return duration_mth_init() + t
[docs] def duration(t): """Completed policy years at the beginning of month t, ``duration_mth(t) // 12``. 0 throughout the first policy year, as in lifelib, and negative before issue. """ return duration_mth(t) // 12
[docs] def policy_year(t): """y: the policy year containing month t, the 1-based contractual label. ``duration(t) + 1``. Derived, never indexed by: it is what the policy-year-keyed schedules -- the COI scale, the lapse table, ``wd_first_year``, ``loan_first_year``, the no-lapse period -- are looked up with. It is 0 or less before issue, where no table is read by it: each reader is called inside cover only (:func:`is_active`). """ return duration(t) + 1
[docs] def age(t): """The attained age (ANB) in month t: ``age_at_entry() + duration(t)``. Attained age increments on the policy anniversary, not on the birthday, which is the ANB convention the whole model is built on **[std]** (spec Table 1, F1). It is the issue age throughout the first policy year, and below it before issue, where no table is read at it. """ return age_at_entry() + duration(t)
[docs] def maturity_mth(): """The policy month at which the projection ends, the first at attained age 121. ``12 * (maturity_age - age_at_entry())``: 912 at issue age 45. The projection runs to attained age 121 **[std]**, the notes' [unverified] maturity inference (spec F5), so the last month of the frame, ``maturity_mth() - 1``, is the last at attained age 120. It is ``IUL_US_S``'s frame from issue, counted on the policy clock; :func:`proj_len` counts from the valuation date instead. The contract is described as continuing in force at 121 with no further charges, so the horizon truncates the run rather than terminating the policy: where lives survive the last month, the count and the account value they carry into this month are kept (see :func:`pols_if_at`). Premiums and charges cease at ``charges_cease_age``, a Reference of its own, 121 too as shipped, which may be set inside the frame. """ return 12 * (maturity_age - age_at_entry()) # noqa: F821
[docs] def proj_len(): """The number of months from the valuation date to the end of the projection. ``maturity_mth() - duration_mth_init()``: 912 for a policy issued at age 45 at the valuation date, 852 for point 6, in force 60 months, and 937 for point 12, issued 25 months after the valuation date. The frame is ``t = 0, 1, ..., proj_len() - 1``; ``proj_len()`` is its exclusive end, the row count of every result table, and ``proj_len() - 1`` is the frame's last month, the last at attained age 120. The contract is described as continuing in force at 121 with no further charges, so the horizon truncates the run rather than terminating the policy; :func:`pols_maturity` is identically zero, and the count and the account value the survivors carry into ``t = proj_len()`` are kept (see :func:`maturity_mth`). Six kinds of point raise here, naming the point, rather than projecting, each checked in this order: one to be issued at or past attained age 121, which would never be in cover, ``maturity_mth() <= 0``, so that a point issued past it is refused by this rule whenever it is to be issued; one at or past the end of the projection at the valuation date; one whose planned withdrawal is above 0 and below the withdrawal fee, ``wd_fee``, which the fee would exceed -- the account would be debited the withdrawal, less than the fee the insurer books, and the policyholder paid nothing, so that ``IUL_US_S``'s own account value roll-forward and margin identity fail on such a point; one in force whose segment ladder in ``inforce_segments_sec.csv`` does not hold exactly one row for each of its last ``min(seg_term_mth, duration_mth_init())`` months, slots 1 to that, a segment a month however little it was swept; and one issued below ``issue_age_min``, 0, or above ``issue_age_max``, 85, the issue ages ``product-spec.md`` admits. ``IUL_US_S`` projects any age its tables serve, but the compiled model's caches are sized from the youngest issue age (``spec_sec.py``), so a younger point, whose frame and policy years run longer, would read past them; ``Data`` refuses an age below 0 first, so at the shipped value that rule binds only once the Reference is raised. The oldest sizes nothing, and is the contract's. The two issue-age rules come after the four of stage ``E``, so that every message stage ``E`` gave a point it still gives. An in-force extract should carry none of them. These are rules of the product, read from this Space's References, where ``Data`` checks the tables. The ladder's counts are compared as ``Data`` elements, not held in locals, and the file is named as shipped, so that the formula keeps no Python object compiled. """ if maturity_mth() <= 0: raise ValueError( f"point_id {point_id()}: age_at_entry {age_at_entry()} " f"is at or past maturity_age, {maturity_age}: " # noqa: F821 f"a policy issued there would never be in cover") n = maturity_mth() - duration_mth_init() if n <= 0: raise ValueError( f"point_id {point_id()}: duration_mth {duration_mth_init()} " f"is at or past the end of the projection, policy month " f"{maturity_mth()}, attained age {maturity_age}") # noqa: F821 if 0 < wd_pp_mth() < wd_fee: # noqa: F821 raise ValueError( f"point_id {point_id()}: wd_pp {wd_pp_mth()} is above 0 and " f"below wd_fee, {wd_fee}: a withdrawal pays its fee out of " # noqa: F821 f"itself, so it must be at least the fee") want = min(seg_term_mth, max(duration_mth_init(), 0)) # noqa: F821 if (data.inforce_segment_count()[idx] != want # noqa: F821 or data.inforce_segment_last()[idx] != want): # noqa: F821 raise ValueError( f"point_id {point_id()}: inforce_segments_sec.csv " f"holds {data.inforce_segment_count()[idx]} segments, its last in slot " f"{data.inforce_segment_last()[idx]}, where a policy in force " # noqa: F821 f"{max(duration_mth_init(), 0)} months holds one a month for its last " f"{want}, slots 1 to {want}") if age_at_entry() < issue_age_min: # noqa: F821 raise ValueError(f"point_id {point_id()}: issue age {age_at_entry()} is below " f"issue_age_min, {issue_age_min}") # noqa: F821 if age_at_entry() > issue_age_max: # noqa: F821 raise ValueError(f"point_id {point_id()}: issue age {age_at_entry()} is above " f"issue_age_max, {issue_age_max}") # noqa: F821 return n
[docs] def t_entry(): """The first month the policy is on the books: ``max(0, -duration_mth_init())``. 0 for a point in force at the valuation date or issued at it, ``k`` for one issued ``k`` months later. It is the base of every recursion: the count, the account value, the fixed account, the collateral, the loan, each live segment and its running totals, the face, the two premium accumulators and the MEC latch all open there, from the model point's opening state and its segment ladder on a point in force and from the issue values on any other. No cell reads a month before it: a segment created before the valuation date is read from the ladder, never from a month before ``t = 0``. """ return max(0, -duration_mth_init())
[docs] def is_active(t): """Whether month t is inside cover: issued, and inside the projection. ``0 <= duration_mth(t) < maturity_mth()``, false before issue and from ``t = proj_len()`` on. Outside cover every count, balance, segment, charge, premium, withdrawal, loan draw, credit, decrement rate, decrement, claim and flow is zero and every flag false, :func:`seg_count` the int 0, and no table is read at a policy year or an attained age the policy does not have; the clocks and the inputs read on the valuation clock and the level policy fee, :func:`expense_pol_mth_at`, keep their values, and the two lapse multipliers their neutral 1.0. The two exceptions are the opening values of the month after the frame, the count and the account value carried into ``t = proj_len()``, which the roll-forwards read (see :func:`pols_if_at` and :func:`av_pp_at`). """ return 0 <= duration_mth(t) < maturity_mth()
[docs] def is_guaranteed_basis(): """Whether the run uses class (a) contractual guarantees only. ``basis`` is ``CURRENT`` in the base run, so the current non-guaranteed scales apply. Setting it to ``GUARANTEED`` switches the fixed-account rate to 1.00%, the cap to 2.00%, the premium load to 8%, the policy fee to $15, the per-unit charge to $0.40 in all years and the COI scale to its guaranteed maximum -- the notes' "guaranteed-basis projections use only this class". Key sensitivity 1 in the notes is exactly how far apart the two runs are. ``basis`` holds a code, as ``IUL_US_S``'s holds the text it is named for (the Space docstring's *Codes*), and any other value is refused, ``"invalid basis"``, as there. """ if basis == CURRENT: # noqa: F821 return False elif basis == GUARANTEED: # noqa: F821 return True else: raise ValueError("invalid basis")
[docs] def load_prem_rate(): """l_prem: the premium load rate, 5% current **[std]** / 8% guaranteed **[std]** (F12). The current rate sits in the model point table because the load is itself a non-guaranteed element re-declarable under ASOP 2 [REG-R26]: ``Data.load_prem_rate`` at the point. """ if is_guaranteed_basis(): return load_prem_rate_guar # noqa: F821 return float(data.load_prem_rate()[idx]) # noqa: F821
[docs] def fixed_rate_ann(t): """i_fix: the fixed (holding) account annual effective rate. 4.50% current [S2], 1.00% guaranteed [S2]. A non-guaranteed element; the base deterministic run holds the snapshot level, as the notes prescribe. An economic input, read at month ``t`` on the **valuation** clock, the same month for every point, as a re-declared rate would apply; level as shipped, so it holds its value outside cover. """ if is_guaranteed_basis(): return guar_rate_ann # noqa: F821 return fixed_rate_curr # noqa: F821
[docs] def inv_return_mth(t): """The monthly fixed-account rate, ``(1 + i_fix)^(1/12) - 1`` **[std]** conversion. 0.0036748 at the 4.50% current rate [S2]. The name follows ``CashValue_SE``; only the fixed account and the loan collateral account earn it -- segments earn no interim interest at all, which is what the 0% floor design buys [S2]. """ return (1 + fixed_rate_ann(t)) ** (1 / 12) - 1
[docs] def guar_rate_mth(): """i_gm: the monthly guaranteed rate, ``(1 + i_g)^(1/12) - 1`` at i_g = 1.00% [S2].""" return (1 + guar_rate_ann) ** (1 / 12) - 1 # noqa: F821
[docs] def naar_factor(): """``1 + i_gm``; ``v_g = 1 / naar_factor()`` is the notes' one-month discount. The death benefit is discounted one month at the **guaranteed** rate, never the credited or index rate -- the universal life base convention, carried over unchanged. 1.0008295 at the 1.00% guarantee [S2]. """ return 1 + guar_rate_mth()
[docs] def loan_rate_mth(): """The monthly charged loan rate, ``(1 + i_L^c)^(1/12) - 1``, at 3.00% **[std]** (F18). A Reference of the run, level in every month. """ return (1 + loan_rate_ann) ** (1 / 12) - 1 # noqa: F821
[docs] def loan_credit_rate_ann(t): """i_L^e: the rate credited on loan collateral, 2.00% years 1-10, 3.00% after **[std]**. The standardization keeps the universal carrier pattern of a ~1% net loan spread early grading to a 0% "wash" from year 11 [S3][S5][S7] (F18). A term of the contract, so it steps on the **policy** year. Zero outside cover, before the policy year is compared: before issue the valuation clock reaches policy years the policy does not have. """ if not is_active(t): return 0.0 if policy_year(t) <= loan_credit_step_year: # noqa: F821 return loan_credit_rate_ann_1 # noqa: F821 return loan_credit_rate_ann_2 # noqa: F821
[docs] def loan_credit_rate_mth(t): """The monthly loan collateral credited rate, ``(1 + i_L^e)^(1/12) - 1``.""" return (1 + loan_credit_rate_ann(t)) ** (1 / 12) - 1
[docs] def index_cap_at(t): """c: the cap in force, 10.00% current [S2] / 2.00% guaranteed [S2] (F8). The current cap is a **snapshot**: observed 10.00%-13.75% across carriers and print dates [S2][S3][S4][S5][S7], and re-declared at every segment start [S3][S4]. The base run holds it level; a cap re-declaration module driven by an option budget is described in the notes but not implemented, because the notes supply neither an option pricing model nor a net investment earnings rate path. Read at month ``t`` on the **valuation** clock, the cap declared then: a segment created in month ``t`` is capped at ``index_cap_at(t)`` at its maturity, twelve months on (:func:`seg_index_cap`), and a segment created before the valuation date at the cap its ladder row carries, :func:`seg_index_cap_init`. Level as shipped, so it holds its value outside cover. """ if is_guaranteed_basis(): return index_cap_guar # noqa: F821 return index_cap_curr # noqa: F821
[docs] def index_level(t): """I(t): the S&P 500 price-return index level at monthiversary t [S2][S3]. The base deterministic run grows the index at a level ``index_return_ann`` a year along the **valuation** clock: ``index_level_init * (1 + index_return_ann)^(t / 12)``, so ``index_level_init`` is the level at the valuation date, one path for every point, and every segment matures at the same point-to-point return. 6.40% is the carrier-published 1988-2023 lookback for the 10%-cap account [S2]. ``IUL_US_S`` reads the path at ``duration_mth(t)``, a path of each point's own from its issue, which is the same path on a point issued at the valuation date. Moving the path moves no credit, a ratio of two levels on one path: a segment created before the valuation date carries its start level on this path in its ladder row (:func:`seg_index_start`). **This cell is the single point of substitution.** Override it, a formula override, which only modelx can make (compiled, edit the formula and rebuild), with a historical or simulated path, keyed by the months from the valuation date, and every segment created in the frame follows; the ladder's start levels are inputs, which do not follow an override, so an extract's ``seg_index_start_init`` must be on the overriding path: the notes' stochastic module (real-world lognormal, mu = 6.0%, sigma = 16% **[std]**) is a driver around the model, not a formula inside it. Remember what the notes say about the level rate: AG 49-A bounds what may be *illustrated*, not what will be *credited* [R1][R6], and because the cap truncates the right tail while the floor only offsets the left, a deterministic run at the illustrated rate overstates credits against a stochastic mean at matched expected index growth. A function of the clock alone, so it holds its value outside cover. """ return index_level_init * (1 + index_return_ann) ** (t / 12) # noqa: F821
[docs] def index_change(index_start, index_end): """r = I(m+12) / I(m) - 1: the point-to-point index change over a segment term. Price return, dividends excluded [S2][S3]. Takes the two index levels rather than a month so that the worked example's own levels -- 4,500.00 to 5,040.00 in scenario A, to 3,825.00 in scenario B -- can be put through the same formula the projection uses. An engine cell of ``IUL_US_S``'s, kept for its worked example and for the comparison with it (the Space docstring's *Reporting cells*): no projection cell calls it, and :func:`seg_return` computes the same ratio for the segment maturing in month ``t``. """ return index_end / index_start - 1
[docs] def index_credit_rate(index_return, cap=None): """cr_k = max(f, min(c, p x r)): the credited rate for one segment [S2][S3][R1]. Floor 0%, participation 100%, cap per :func:`index_cap_at` [S2]. ``cap`` defaults to the cap in force at ``t = 0``, ``IUL_US_S``'s engine, kept unchanged for its worked example -- pass ``index_cap_guar`` for the guaranteed-basis credit; the notes price both on the worked example, at 10.00% and 2.00%. An engine cell, kept for that example and for the comparison with ``IUL_US_S``: no projection cell calls it, and :func:`seg_credit_rate` computes the same rate, in the same order of bounds, for the segment maturing in month ``t``, at the cap declared at its creation. This is where the two-sided truncation lives: the cap binds on the way up, the floor on the way down, and the historical frequency of a 0% credit for a single index allocation was 12.55%-23.81% in a carrier's 2005-2017 issue-date study [S8]. """ c = index_cap_at(0) if cap is None else cap return max(index_floor, min(c, index_par * index_return)) # noqa: F821
[docs] def seg_credit_base(seg_bal_init, seg_deductions, conv=None): """The segment balance the index credit is applied to. ``REMAINING`` **[std]**, the baseline ``seg_bal_init - seg_deductions``: the actual balance left at maturity, so amounts withdrawn, borrowed or deducted mid-segment earn no index credit (withdrawal and loan forfeiture [S3]; extension to deductions **[std]**). ``ADJ_BEGIN``, the documented variation ``seg_bal_init - seg_deductions / 2``: one carrier's contractual adjusted beginning value, which subtracts withdrawals and loan transfers in full but **one half** of the monthly deductions taken during the segment [S3]. Pass ``seg_bal_init`` already net of withdrawals and loan transfers, as :func:`index_credit_pp` takes it. The notes list picking one and keeping the death benefit, cash value and credit formulas consistent with it among the modeling pitfalls; ``seg_credit_base_conv`` is the Reference that records the choice, a code (the Space docstring's *Codes*), which ``conv`` defaults to. An engine cell, kept for ``IUL_US_S``'s worked example and for the comparison with it: no projection cell calls it, and :func:`index_credit_pp` computes the same base inline, refusing a convention neither code names with the same ``"invalid credit base"``. """ k = seg_credit_base_conv if conv is None else conv # noqa: F821 if k == REMAINING: # noqa: F821 return seg_bal_init - seg_deductions elif k == ADJ_BEGIN: # noqa: F821 return seg_bal_init - seg_deductions / 2 else: raise ValueError("invalid credit base")
[docs] def index_credit(seg_bal_init, seg_deductions, index_return, conv=None, cap=None): """Credit_k = cr_k x credit base: the index credit paid at a segment's maturity. The engine form, taking the segment's opening balance (net of any withdrawals and loan transfers), the deductions charged to it over its term, and its point-to-point index change: :func:`index_credit_rate` times :func:`seg_credit_base`. An engine cell, kept for ``IUL_US_S``'s worked example, which prices one segment's credit at both caps through it, and for the comparison with ``IUL_US_S``, whose projection calls it: no projection cell here calls it, and :func:`index_credit_pp` computes the same product, the rate first, then the base. """ return (index_credit_rate(index_return, cap) * seg_credit_base(seg_bal_init, seg_deductions, conv))
[docs] def seg_matured_value(seg_bal_init, seg_deductions, index_return, conv=None, cap=None): """The matured segment value: remaining balance plus the index credit. ``S_{k,m+12} x (1 + cr_k)`` under the baseline credit base, which is the value that rolls into the fixed account and is swept back into a new segment under the standing allocation instruction **[std]** (spec F11). An engine cell, kept for ``IUL_US_S``'s worked example, which alone calls it; :func:`seg_roll_pp` is the projection's matured value. """ return (seg_bal_init - seg_deductions + index_credit(seg_bal_init, seg_deductions, index_return, conv, cap))
[docs] def prem_persistency(t): """The fraction of the planned premium actually paid in policy year y **[std]**. ``0.98^(y - 1)``: the notes give premium persistency in closed form rather than as a table, compounding at 98% a year. Premium persistency is *the* behavior dimension unique to flexible-premium products; the 2015-2021 LIMRA/SOA UL study is the recommended public calibration base [REG-R21] and the level here is a placeholder. A rule of the contract's years, so it steps on the **policy** year: a policy in force pays the persistency of its own year, not of the valuation date's. The funding-stop state the notes pair with this factor -- probability 1% a year, after which the policy runs charge-only -- is a **second account value path** the notes do not say how to blend with the first, and is not implemented. Zero outside cover, before the policy year is read. """ if not is_active(t): return 0.0 return prem_persistency_rate ** (policy_year(t) - 1) # noqa: F821
[docs] def premium_pp(t): """P_t: the gross premium per policy received at BOM of month t. Annual mode **[std]**: the whole planned premium falls at BOM of the first month of each policy year, ``duration_mth(t) % 12 == 0``, and every other month is zero. Monthly mode: a twelfth of the planned annual premium falls at BOM of every month, ``premium_pp_ann / 12`` times :func:`prem_persistency`, as on points 4, 7 and 12. ``LEVEL`` The planned premium times :func:`prem_persistency`, in either mode. ``SINGLE`` One premium in the issue month, capped at the guideline single premium. ``TARGET`` As ``LEVEL`` but capped so cumulative premium stays inside the guideline premium limit **[std]**; the cap looks at the accumulator's opening value -- ``cum_prem_pp(t - 1)``, or, in the first month on the books, :func:`t_entry`, :func:`cum_prem_init`, the premiums less withdrawals paid before the valuation date, 0 at issue -- so there is no circularity, and a TARGET point in force near its limit collects only what the limit still has room for. Zero from attained age ``charges_cease_age``, 121 as shipped, when charges cease and premiums are no longer accepted (spec F5), and zero outside cover. The pattern and the mode are read through their decodes, :func:`is_single_premium`, :func:`is_level_premium`, :func:`is_target_premium`, :func:`is_annual_premium` and :func:`is_monthly_premium`, not as text; a value none of them knows raises, as ``IUL_US_S``'s does. """ if not is_active(t) or age(t) >= charges_cease_age: # noqa: F821 return 0.0 if is_single_premium(): return min(premium_pp_ann(), gsp()) if duration_mth(t) == 0 else 0.0 if is_annual_premium(): if duration_mth(t) % 12 != 0: return 0.0 gross = premium_pp_ann() * prem_persistency(t) elif is_monthly_premium(): gross = premium_pp_ann() / 12 * prem_persistency(t) else: raise ValueError("invalid premium mode") if is_level_premium(): return gross elif is_target_premium(): paid = cum_prem_pp(t - 1) if t > t_entry() else cum_prem_init() return min(gross, max(0.0, gpt_limit(t) - paid)) else: raise ValueError("invalid premium type")
[docs] def prem_to_av_pp(t): """NP_t = P_t (1 - l_prem): the net premium, credited to the fixed account. The fixed account doubles as the interim / holding account: net premium sits there at the declared fixed rate until the next monthiversary sweep moves it into a segment [S1] **[std]** (spec F10). """ return premium_pp(t) * (1 - load_prem_rate())
[docs] def prem_to_av(t): """Net premium credited to account values, for the policies in force.""" return prem_to_av_pp(t) * pols_if(t)
[docs] def premiums(t): """Premium income at BOM of month t, weighted by the in force at BOM.""" return premium_pp(t) * pols_if(t)
[docs] def wd_pp(t): """W_t: the partial withdrawal per policy at BOM of month t, **gross of the fee**. A constant monthly amount from :func:`wd_first_year`, :func:`wd_pp_mth`, the model point's ``wd_pp`` column, and **0 in the baseline** **[std]**: the notes give no withdrawal utilization pattern, so the mechanics are implemented and the behaviour is left to the data. Model point 5 switches it on. The account is debited ``W_t``; the policyholder receives ``W_t - 25`` and the insurer keeps the $25 fee [S3]. This differs from the universal life chassis, where the fee is charged on top of the withdrawal -- these notes write the withdrawal outflow as ``W_t - $25 fee``, so the fee is inside ``W_t`` here. Zero from attained age ``charges_cease_age``, and zero outside cover, before the policy year is compared: before issue the valuation clock reaches policy years the policy does not have. """ if not is_active(t) or policy_year(t) < wd_first_year(): return 0.0 if age(t) >= charges_cease_age: # noqa: F821 return 0.0 return wd_pp_mth()
[docs] def wd_fee_pp(t): """The $25 withdrawal fee, charged only in a month with a withdrawal [S3]. Retained by the insurer, so it is part of :func:`margin_expense`, not of :func:`claims`. It is not an extra debit to the account value: it comes out of ``W_t``. """ return wd_fee if wd_pp(t) > 0 else 0.0 # noqa: F821
[docs] def loan_new_pp(t): """B_t: a new standard loan taken at BOM of month t **[std]**. The notes' distribution-scenario module borrows a level amount annually from a start age **[std]**; here that is :func:`loan_new_pp_ann`, the model point's ``loan_new_pp_ann``, at each policy anniversary from the first month of policy year :func:`loan_first_year`. **Zero in the baseline** -- the notes set loan utilization to none -- and switched on by model point 5. Participating (indexed) loans are a documented variation, not modeled: the baseline uses standard loans only **[std]** (F18), which decouples loan modeling from index scenarios. Zero outside cover, before the policy year is compared. """ if not is_active(t) or policy_year(t) < loan_first_year(): return 0.0 if duration_mth(t) % 12 != 0: return 0.0 return loan_new_pp_ann()
[docs] def face_reduction_pp(t): """The face reduction a withdrawal forces under Option A, dollar for dollar **[std]**. Standard universal life practice, stated in the product spec but not explicit in the retrieved brochures. Under Option B the withdrawal reduces the account value only and this is zero. Never more than the face entering the month, which is the previous month's :func:`sum_assured_at`, or, in the first month on the books, :func:`t_entry`, the face in force at the valuation date, :func:`sum_assured_init`, on a point in force, and the face at issue, :func:`sum_assured`, on any other. The option is read through its decode, :func:`is_db_option_a`. Zero outside cover. """ if not is_active(t): return 0.0 if not is_db_option_a() or wd_pp(t) <= 0: return 0.0 if t > t_entry(): opening = sum_assured_at(t - 1) elif duration_mth_init() > 0: opening = sum_assured_init() else: opening = sum_assured() return min(wd_pp(t), opening)
[docs] def sum_assured_at(t): """F(t+1): the face amount at the end of month t, after any withdrawal-driven cuts. A closing balance: the opening face of month ``t`` is the previous month's, and in the first month on the books, :func:`t_entry`, the face in force at the valuation date, :func:`sum_assured_init`, on a point in force, and the face at issue, :func:`sum_assured`, on any other, less this month's Option A reduction. Face increases, elective decreases and option changes are not modeled, so the withdrawal reduction is the only movement; it never takes more than the opening face, so the face reaches 0 at the least and stays there. Zero outside cover. """ if not is_active(t): return 0.0 if t > t_entry(): opening = sum_assured_at(t - 1) elif duration_mth_init() > 0: opening = sum_assured_init() else: opening = sum_assured() return max(0.0, opening - face_reduction_pp(t))
[docs] def units(t): """The face amount in $1,000 units, ``sum_assured_at(t) / 1000``. The per-unit charge is quoted per $1,000 of face per month, so it multiplies this. The surrender charge is quoted per $1,000 of **initial** face, because face decreases do not reduce it [S3]; see :func:`surr_charge_pp`. """ return sum_assured_at(t) / 1000
[docs] def corridor_factor(t): """kappa_x: the IRC 7702(d) corridor factor at the attained age [R4]. 250% at ages 0-40 grading to 100% at 90-95, read at the attained age of month t by :func:`corridor_factor_at`. Only the Guideline Premium Test is modeled (spec F4), so any other ``qual_test`` raises rather than being treated as GPT, in whatever month, since it is a fault of the point; the test is read through its decode, :func:`is_gpt`. High funding drives the corridor rather than the face amount, which raises the death benefit, the net amount at risk and hence the cost of insurance: the notes list omitting this among the pitfalls, because it overstates late-duration account values and understates charges. Zero outside cover, before the table is read. """ if not is_gpt(): raise ValueError("invalid qual_test") return corridor_factor_at(age(t)) if is_active(t) else 0.0
[docs] def corridor_factor_at(a): """kappa at attained age a, from *corridor_factors.csv*: the table's one reader. ``Data.corridor_factor_array()`` at the age, the table padded from age 0, so that the age is the index. Ages outside the table take its nearest row: the first and last ages ``data.corridor_age_first()`` and ``data.corridor_age_last()`` give, which they read from the table's key column once the keys and the factors are checked, before any factor is read. So the padding is never read, and no age below 0 is either: ``Data`` refuses a table whose first age is negative. The last is asked for first, since it runs the checks and the first is counted back from it. Keyed by the attained age, so the table is read once an age rather than once a month; :func:`corridor_factor` calls it inside cover only. """ last = data.corridor_age_last() # noqa: F821 a = min(max(a, data.corridor_age_first()), last) # noqa: F821 return float(data.corridor_factor_array()[a]) # noqa: F821
[docs] def db_pp(t): """DB_t: the death benefit per policy after the corridor test [S3][R4]. ``max(option_db, kappa_x x AV'_t)`` where ``option_db`` is the face amount under Option A and face plus account value under Option B, and ``AV'_t`` is the account value after premium, the maturity credit and any withdrawal, and **before** the monthly deduction. Measuring the account value at that point is what removes the circularity: under Option B the death benefit depends on the account value and the net amount at risk on the death benefit, but with this ordering neither depends on the deduction. During a segment the death benefit reflects the segment balance **without** unrealized index credit [S3]: with a 0% floor design segments simply carry no interim interest, so nothing extra is needed here. ``IUL_US_S``'s formula, with no floor on the account value: an exhausted account's ``AV'_t`` below zero leaves the corridor's amount at 0 or below, and the face wins, which ``Data`` keeps so by refusing a corridor factor below 0. The option is read through its decodes, :func:`is_db_option_a` and :func:`is_db_option_b`, not as text. Zero outside cover, before the corridor table is read. """ if not is_active(t): return 0.0 av = av_pp_at(t, BEF_FEE) # noqa: F821 if is_db_option_a(): opt = sum_assured_at(t) elif is_db_option_b(): opt = sum_assured_at(t) + av else: raise ValueError("invalid db_option") return max(opt, corridor_factor(t) * av)
[docs] def net_amt_at_risk(t): """NAAR_t = max(0, DB_t x v_g - AV'_t), the universal life base convention. The death benefit is discounted one month at the **guaranteed** rate (:func:`naar_factor`) and the account value is measured **before** the monthly deduction. Using the credited or index rate in the discount, or the post-deduction account value, makes the cost of insurance implicit and requires iteration, and produces small systematic errors. """ return max(0.0, db_pp(t) / naar_factor() - av_pp_at(t, BEF_FEE)) # noqa: F821
[docs] def coi_rate_guar(t): """The guaranteed maximum monthly COI rate per $1,000 of net amount at risk. The notes set the guaranteed basis at 2017 CSO ANB smoker-distinct ultimate **[std]**/[REG-R17]. That table is licensed and is not reproduced here: the shipped scale is illustrative **[std]**, of realistic magnitude and shape, and is swapped by replacing *coi_rates.csv*. Read at the policy year of month t by :func:`coi_rate_guar_py`, where policy years beyond the table take its last row; zero outside cover, before the scale is read. """ return coi_rate_guar_py(policy_year(t)) if is_active(t) else 0.0
[docs] def coi_schedule(): """The number of this point's guaranteed COI scale, its row of the COI array. ``Data.coi_schedule`` at the point: the schedules of *coi_rates.csv*, one for each ``sex``, ``rate_class`` and ``age_at_entry`` it holds, numbered from 1 in the order of those keys, and 0 where the table has no scale for the point's own, which :func:`coi_rate_last_year` refuses where a rate is read. It stands for ``IUL_US_S``'s ``coi_rate_scale``, a Series sliced from the table, which no compiled cell can hold: :func:`coi_rate_guar_py` reads the scale at this row and the year. """ return int(data.coi_schedule()[idx]) # noqa: F821
[docs] def coi_rate_guar_py(y): """The guaranteed maximum monthly COI rate in policy year y, from the point's scale. ``Data.coi_rate_array()`` at the point's :func:`coi_schedule` and the year, each schedule padded from year 0, so that the year is the column. Policy years beyond the scale take its last row, :func:`coi_rate_last_year`, which is asked for first, so that a projection meets the check of the table's keys, and the refusal of a point whose cell the table lacks, before any rate is read. A year below 1, where ``IUL_US_S``'s slice raised ``KeyError``, is refused, naming the point and the year, so that the padding is never read. The scale's one reader, keyed by the contractual policy year; :func:`coi_rate_guar` calls it inside cover only. """ last = coi_rate_last_year() if y < 1: raise ValueError(f"point_id {point_id()}: coi_rates.csv has no rate for policy " f"year {y}") return float(data.coi_rate_array()[coi_schedule(), min(y, last)]) # noqa: F821
[docs] def coi_rate_last_year(): """The last policy year of this point's guaranteed COI scale: its extent. ``Data.coi_rate_last_years`` at this point's :func:`coi_schedule`, the last year of its scale, which ``Data`` reads from the table's key columns once it has checked the keys and the rates. 76 on the shipped anchor cell, whose scale runs to attained age 120. A point the table has no scale for, schedule 0, has a last year of 0, and is refused here, naming it and its issue age, where ``IUL_US_S`` raises pandas' ``KeyError``: when its first COI rate is read, and not before, since a point valued at or past ``charges_cease_age`` never reads one, and ``IUL_US_S`` projects it. Stage ``E``'s message quoted the point's ``sex`` and ``rate_class`` too, which a projection formula cannot read here: each is a label, a reporting cell's. The element is compared, and ``int`` of it returned, rather than held in a local first, which a formula that also builds a message would keep a Python object compiled. """ if data.coi_rate_last_years()[coi_schedule()] < 1: # noqa: F821 raise ValueError(f"point_id {point_id()}: coi_rates.csv has no rates for its sex, " f"rate_class and age_at_entry {age_at_entry()}") return int(data.coi_rate_last_years()[coi_schedule()]) # noqa: F821
[docs] def coi_rate(t): """coi_t: the monthly COI rate in force, per $1,000 of net amount at risk. ``coi_curr_factor`` (65% **[std]**) times the guaranteed maximum on the current basis; the guaranteed maximum itself on the guaranteed basis. Carrier COI tables are not public [S3] and re-rating is governed by ASOP 2 [REG-R26], so the ratio is a pure modeling assumption and one of the notes' dominant sensitivities. Note the units: per $1,000 of net amount at risk per **month**, so it is divided by 1,000 in :func:`coi_pp`. It is not comparable with ``CashValue_SE.coi_rate``, which is a rate per unit of account value. """ if is_guaranteed_basis(): return coi_rate_guar(t) return coi_curr_factor * coi_rate_guar(t) # noqa: F821
[docs] def coi_pp(t): """COI_t = coi_t x NAAR_t / 1000: the cost of insurance charge per policy. Zero from attained age ``charges_cease_age``, when charges cease, and zero outside cover, before the scale is read. """ if not is_active(t) or age(t) >= charges_cease_age: # noqa: F821 return 0.0 return coi_rate(t) / 1000 * net_amt_at_risk(t)
[docs] def coi(t): """Cost of insurance charges deducted from account values, for the policies in force.""" return coi_pp(t) * pols_if(t)
[docs] def rider_charge_pp(t): """Rider charges, 0 in the baseline **[std]**. The notes carry this term in the monthly deduction so rider modules can be added without changing the recursion; every rider in the product spec is out of the baseline. """ return 0.0
[docs] def expense_pol_mth_at(t): """e_pol: the monthly policy fee, $10 current [S3][S5] / $15 guaranteed **[std]**. The notes' F13. Level in every month, an input that holds its value outside cover, as the fixed-account rate and the cap do; :func:`maint_fee_pp`, its one reader, is zero there. """ if is_guaranteed_basis(): return expense_pol_mth_guar # noqa: F821 return expense_pol_mth # noqa: F821
[docs] def expense_unit_mth_at(t): """e_unit: the per-unit charge per $1,000 of face per month (F14). $0.30 in policy years 1-10 and nothing thereafter on the current basis; $0.40 in **all** years on the guaranteed basis. The structure -- charged for the first ten years currently, guaranteed for all years -- is sourced [S3][S5]; the dollar scales live in policy data pages and are not public, so the levels are **[std]**. A term of the contract, so it steps on the **policy** year. Zero outside cover, before the policy year is compared. """ if not is_active(t): return 0.0 if is_guaranteed_basis(): return expense_unit_mth_guar # noqa: F821 if policy_year(t) <= expense_unit_step_year: # noqa: F821 return expense_unit_mth_1 # noqa: F821 return expense_unit_mth_2 # noqa: F821
[docs] def maint_fee_pp(t): """The non-COI part of the monthly deduction per policy. ``e_pol + e_unit x F/1000 + rider charges``. The name follows ``CashValue_SE.maint_fee``: this is a *charge* against the account value and therefore insurer income. It is not :func:`expenses`, which is the insurer's own outgo. Zero from attained age ``charges_cease_age``, when charges cease, and zero outside cover. The policy fee, :func:`expense_pol_mth_at`, is level, an input that holds its value in every month; the guard here keeps it off the months outside cover. """ if not is_active(t) or age(t) >= charges_cease_age: # noqa: F821 return 0.0 return (expense_pol_mth_at(t) + expense_unit_mth_at(t) * units(t) + rider_charge_pp(t))
[docs] def maint_fee(t): """Non-COI monthly charges deducted from account values, for the policies in force.""" return maint_fee_pp(t) * pols_if(t)
[docs] def mth_deduction_pp(t): """MD_t = e_pol + e_unit x F/1000 x 1{yr<=10} + coi_t x NAAR_t / 1000. :func:`maint_fee_pp` plus :func:`coi_pp`, taken at BOM. The deduction at the start of month t pays for month t's coverage. """ return maint_fee_pp(t) + coi_pp(t)
[docs] def mth_deduction(t): """Monthly deductions taken from account values, for the policies in force.""" return mth_deduction_pp(t) * pols_if(t)
[docs] def draw_pp(t): """The total amount leaving the fixed account and segments at step 3 of month t. The withdrawal (gross of its fee) plus the collateral for any new standard loan. The loan collateral does not leave the *account value* -- it moves into :func:`lca_pp` -- but it does leave the fixed account and the segments, and it is sourced by the same rule: fixed account first, then pro rata across live segments, the order one carrier gives for loans [S3]. Applied to the withdrawal the rule is **[std]**: that carrier takes withdrawals pro rata across all unloaned accounts [S3]. """ return wd_pp(t) + loan_new_pp(t)
[docs] def draw_from_seg_pp(t): """The part of the step-3 draw sourced pro rata from live segments. Only what the fixed account cannot cover, and never more than the live segments hold (see :func:`draw_pp`). Being step 3 it has the **first** claim on the pool; the step-6 deduction is capped against what is left after it (:func:`mth_deduction_from_seg_pp`). Amounts leaving a segment mid-term earn no index credit [S3], which under the baseline credit base happens automatically. """ short = draw_pp(t) - max(0.0, fa_pp_at(t, BEF_WD)) # noqa: F821 if short <= 0: return 0.0 return min(short, max(0.0, seg_bal_active_pp(t)))
[docs] def draw_from_fa_pp(t): """The part of the step-3 draw sourced from the fixed account, taken first. Defined as the residual of :func:`draw_pp` so that the two sources always sum to it exactly; if neither the fixed account nor the segments can cover it, the fixed account carries the excess and goes negative rather than the draw being silently truncated. """ return draw_pp(t) - draw_from_seg_pp(t)
[docs] def mth_deduction_from_seg_pp(t): """The part of the monthly deduction sourced pro rata from live segments **[std]**. The notes' sourcing convention: fixed account first, shortfall pro rata across active segments. Never more than the segments still hold **after** the step-3 draw, which is why the cap is ``seg_bal_active_pp(t) - draw_from_seg_pp(t)`` and not the pool :func:`draw_from_seg_pp` was itself capped against: the withdrawal and the new loan collateral come out of the same segments earlier in the same month, so capping both against the pre-draw pool would let the two together take more than the segments hold. That drives a segment balance negative and, twelve months later, pays a **negative** index credit on it -- a breach of the 0% floor of ``cr_k = max(f, min(c, p x r))`` [S2][R1]. :func:`check_seg_ladder` asserts both consequences away. Whatever the segments cannot cover stays with :func:`mth_deduction_from_fa_pp`, so the fixed account carries the excess and goes negative rather than the deduction being silently truncated -- the notes charge ``MD_t`` in full and hand an uncovered deduction to the grace/lapse cascade, which is not implemented. Carrier practice differs -- one carrier instead half-weights in-segment deductions in its credit base [S3] -- and the notes list picking one and keeping the formulas consistent among the modeling pitfalls; see :func:`seg_credit_base`. """ short = mth_deduction_pp(t) - max(0.0, fa_pp_at(t, BEF_FEE)) # noqa: F821 if short <= 0: return 0.0 return min(short, max(0.0, seg_bal_active_pp(t) - draw_from_seg_pp(t)))
[docs] def mth_deduction_from_fa_pp(t): """The part of the monthly deduction sourced from the fixed account, taken first. The residual, so the two sources always sum to :func:`mth_deduction_pp`. """ return mth_deduction_pp(t) - mth_deduction_from_seg_pp(t)
[docs] def seg_bal_active_pp(t): """The live segment balances available to a draw at BOM of month t. The segments born in policy months ``duration_mth(t) - 11`` to ``duration_mth(t) - 1``, valued at the end of month ``t - 1``, where each sat in slot ``duration_mth(t) - 1 - m``. The segment born at ``duration_mth(t) - 12`` is **not** in the pool: it matured at step 2 of this month and its value is already in the fixed account. The segment born this month does not exist yet -- it is created by the sweep at step 7. No segment is born before issue, so the pool is empty in the issue month. In the first month on the books, :func:`t_entry`, a segment born before the valuation date is valued from the segment ladder, :func:`seg_bal_pp_init`, its balance entering month 0. The balances are summed in ``IUL_US_S``'s order, by creation month, in an explicit loop that compensates as Python's ``sum()`` of floats does from Python 3.12, Neumaier's improvement of Kahan's summation, the compensation added at the end where it is a finite number other than zero, ``abs(c) <= 1.7976931348623157e308``, the largest double: so the pool is ``IUL_US_S``'s ``sum()`` bit for bit there, a segment closing on a rounding about zero included, which :func:`seg_share` reads by its test of zero. Compiled, the loop is C on doubles, added in the order written, since nothing in the build lets the compiler reassociate (no ``-ffast-math``), and with no multiply and add fused into one rounding, which the build forbids (``-ffp-contract=off``). Python 3.11's ``sum()`` is a plain fold, which can put such a pool on the other side of zero. Zero outside cover. """ if not is_active(t): return 0.0 d = duration_mth(t) s = 0.0 c = 0.0 for m in range(max(0, d - seg_term_mth + 1), d): # noqa: F821 if t > t_entry(): x = seg_bal_pp(t - 1, d - 1 - m) else: x = seg_bal_pp_init(duration_mth_init() - m) u = s + x if abs(s) >= abs(x): c = c + ((s - u) + x) else: c = c + ((x - u) + s) s = u if c != 0.0 and abs(c) <= 1.7976931348623157e308: s = s + c return s
[docs] def seg_share(t, k): """The pro-rata share of a draw at BOM of month t of the segment in slot k. Its opening balance over the live pool, :func:`seg_bal_active_pp`, and 0 where the pool is not above zero, ``IUL_US_S``'s own test, which a pool closing on a rounding about zero meets either way. Because a pro-rata draw leaves the proportions unchanged, the same shares serve the step-3 draw and the step-6 deduction even though they are taken at different points in the month. ``k`` is the segment's slot in month ``t``, its months since creation, ``duration_mth(t) - m`` for the segment born in policy month ``m``. The opening balance is the segment's at the end of month ``t - 1``, where it sat in slot ``k - 1``, or, in the first month on the books, :func:`t_entry`, the ladder's :func:`seg_bal_pp_init` at slot ``k``, read only for a slot the ladder holds, ``1`` to ``min(seg_term_mth, duration_mth_init())``; any other slot, slot 0, the segment born in the month itself, or one older than the ladder, has a share of 0, as ``IUL_US_S``'s read of a balance outside its segment's life gives. Slot 0 asks for no balance, so no cell reads a slot below 0. """ pool = seg_bal_active_pp(t) if pool <= 0: return 0.0 if k < 1: return 0.0 if t > t_entry(): prev = seg_bal_pp(t - 1, k - 1) elif k <= min(seg_term_mth, duration_mth_init()): # noqa: F821 prev = seg_bal_pp_init(k) else: prev = 0.0 return prev / pool
[docs] def seg_wd_pp(t, k): """The draw of month t out of the segment in slot k: its share of the step-3 draw.""" return draw_from_seg_pp(t) * seg_share(t, k)
[docs] def seg_ded_pp(t, k): """The deduction of month t out of the segment in slot k: its share of the monthly deduction. """ return mth_deduction_from_seg_pp(t) * seg_share(t, k)
[docs] def sweep_pp(t): """Sweep_t = w_ix x FA balance after steps 1-6 **[std]** (spec F10). The monthiversary sweep, which creates this month's segment. Carrier practice varies -- one carrier sweeps on the 15th [S1], another on the first day of a policy month [S3] -- and the baseline standardizes on the monthiversary so segment dates align with monthly processing. A third carrier's charge-holdback in the fixed strategy [S5] is a documented variation and is not modeled. Nothing is swept from a fixed account below zero. Zero outside cover. """ if not is_active(t): return 0.0 return index_alloc_rate() * max(0.0, fa_pp_at(t, BEF_SWEEP)) # noqa: F821
[docs] def seg_new_pp(m): """S_{k,m_k}: the balance of the segment born in policy month m, at its creation. ``m`` is a **policy** month, ``duration_mth`` of the month of the sweep that created the segment. Born in the frame, at or after the valuation date, the segment is that month's sweep, :func:`sweep_pp` at month ``m - duration_mth_init()``, as in ``IUL_US_S``. Born before the valuation date, it is in ladder slot ``k = duration_mth_init() - m``, and its creation balance is what the ladder gives it since, its balance entering month 0 plus the deductions and the draws charged to it: nothing may enter or leave a segment but a deduction, a withdrawal or a loan transfer, which is the closure :func:`check_seg_ladder` asserts. Zero for a month before issue and for a segment matured before the valuation date, which nothing reads. Keyed by the creation month, as in ``IUL_US_S``, where the six cells of a segment in a month are keyed by its slot: one value a segment, which :func:`seg_bal_pp` reads in slot 0 and :func:`index_credit_pp` at maturity. """ d0 = duration_mth_init() if m < 0: return 0.0 if m >= d0: return sweep_pp(m - d0) k = d0 - m if k > seg_term_mth: # noqa: F821 return 0.0 return seg_bal_pp_init(k) + seg_ded_cum_pp_init(k) + seg_wd_cum_pp_init(k)
[docs] def seg_bal_pp(t, k): """S_{k,t+1}: the balance at the end of month t of the segment in slot k. ``S_{k,t+1} = S_{k,t} - MD^seg - W^seg - B^seg``, with **no interim interest**: the 0% floor design credits nothing during the segment term [S2], in contrast with one carrier's in-segment 0.75% [S3], which is a different guarantee and must not be mixed with a 0% annual floor. A closing balance: the value at the end of month ``t`` is the notes' ``S_{k,t+1}``. ``k`` is the segment's slot, its months since creation in month ``t``, ``duration_mth(t) - m`` for the segment born in policy month ``m``: 0 in its creation month, where its balance is its creation balance, :func:`seg_new_pp`, and 11 in the last month it is live. Its balance a month earlier is the same segment's in slot ``k - 1`` at ``t - 1``. Zero outside slots 0 to ``min(11, duration_mth(t))``: below 0, for a segment not yet born, past the policy's months (no segment exists before issue) and past 11, and outside cover. A segment created at ``m`` is live through the end of policy month ``m + 11`` and matures at step 2 of policy month ``m + 12``, before that month's deduction -- so it bears eleven in-segment deductions. The worked example stipulates twelve; see ``products/indexed_ul/model.md``. In the first month on the books, :func:`t_entry`, a segment born before the valuation date opens from the ladder, :func:`seg_bal_pp_init` at its slot, its balance entering month 0. ``IUL_US_S`` keys the cell by the creation month, ``seg_bal_pp(t, m)``; the slot is what lets a compiled cache hold twelve segments a month rather than every creation month of the frame. """ if not is_active(t): return 0.0 d = duration_mth(t) if k < 0 or k > d or k > seg_term_mth - 1: # noqa: F821 return 0.0 if k == 0: return seg_new_pp(d) if t > t_entry(): prev = seg_bal_pp(t - 1, k - 1) else: prev = seg_bal_pp_init(k) return prev - seg_wd_pp(t, k) - seg_ded_pp(t, k)
[docs] def seg_ded_cum_pp(t, k): """Deductions charged to the segment in slot k, through the end of month t. Zero in the creation month itself, slot 0 (the segment is created after that month's deduction), outside the segment's life and outside cover. Its running total a month earlier is the same segment's in slot ``k - 1`` at ``t - 1``. In the first month on the books, :func:`t_entry`, a segment born before the valuation date opens from the ladder, :func:`seg_ded_cum_pp_init` at its slot, the deductions charged to it before month 0. """ if not is_active(t): return 0.0 d = duration_mth(t) if k < 1 or k > d or k > seg_term_mth - 1: # noqa: F821 return 0.0 if t > t_entry(): prev = seg_ded_cum_pp(t - 1, k - 1) else: prev = seg_ded_cum_pp_init(k) return prev + seg_ded_pp(t, k)
[docs] def seg_wd_cum_pp(t, k): """Withdrawals and loan transfers out of the segment in slot k, through month t. Zero in the creation month itself, slot 0, outside the segment's life and outside cover. Its running total a month earlier is the same segment's in slot ``k - 1`` at ``t - 1``. In the first month on the books, :func:`t_entry`, a segment born before the valuation date opens from the ladder, :func:`seg_wd_cum_pp_init` at its slot, the draws out of it before month 0. """ if not is_active(t): return 0.0 d = duration_mth(t) if k < 1 or k > d or k > seg_term_mth - 1: # noqa: F821 return 0.0 if t > t_entry(): prev = seg_wd_cum_pp(t - 1, k - 1) else: prev = seg_wd_cum_pp_init(k) return prev + seg_wd_pp(t, k)
[docs] def seg_bal_tot_pp(t): """The sum of every live segment balance at the end of month t. The segments born in policy months ``max(0, duration_mth(t) - 11)`` to ``duration_mth(t)``, each read at its slot, ``duration_mth(t) - m``, summed in ``IUL_US_S``'s order in the compensated loop :func:`seg_bal_active_pp` sums in, so that the total is ``IUL_US_S``'s ``sum()`` bit for bit from Python 3.12. Zero outside cover. """ if not is_active(t): return 0.0 d = duration_mth(t) s = 0.0 c = 0.0 for m in range(max(0, d - seg_term_mth + 1), d + 1): # noqa: F821 x = seg_bal_pp(t, d - m) u = s + x if abs(s) >= abs(x): c = c + ((s - u) + x) else: c = c + ((x - u) + s) s = u if c != 0.0 and abs(c) <= 1.7976931348623157e308: s = s + c return s
[docs] def seg_count(t): """The number of segments with a positive balance at the end of month t. At most ``seg_term_mth`` (12), the contractual maximum [S4]; zero throughout for a model point with ``index_alloc_rate() == 0``. A segment counts where its balance, read at its slot, is above zero, ``IUL_US_S``'s own test, which a balance closing on a rounding about zero meets by its sign. An int, counted in a loop, and the int 0 outside cover. """ if not is_active(t): return 0 d = duration_mth(t) n = 0 for m in range(max(0, d - seg_term_mth + 1), d + 1): # noqa: F821 if seg_bal_pp(t, d - m) > 0: n = n + 1 return n
[docs] def seg_index_start(t): """I(m): the index level at the creation of the segment maturing in month t. The segment maturing in month ``t`` was born twelve months earlier. Born in the frame, at month ``t - 12``, it started from ``index_level(t - 12)``; born before the valuation date, in ladder slot ``12 - t``, from the start level its ladder row carries, :func:`seg_index_start_init`, on the same path. ``IUL_US_S`` reads ``index_level(t - 12)``, a month of its own frame, since no segment it projects was born before its first month. Zero where nothing matures, in a policy's first twelve policy months, and outside cover. """ if not is_active(t) or duration_mth(t) < seg_term_mth: # noqa: F821 return 0.0 if t - seg_term_mth >= t_entry(): # noqa: F821 return index_level(t - seg_term_mth) # noqa: F821 return seg_index_start_init(seg_term_mth - t) # noqa: F821
[docs] def seg_index_cap(t): """c_m: the cap of the segment maturing in month t, the one declared at its creation. Born in the frame, at month ``t - 12``, the segment is capped at the cap in force then, ``index_cap_at(t - 12)``; born before the valuation date, in ladder slot ``12 - t``, at the cap its ladder row carries, :func:`seg_index_cap_init`. The cap is re-declared at every segment start [S3][S4], and a segment keeps the one declared at its own. ``IUL_US_S`` holds the cap level and its engine reads ``index_cap_at(0)``, the cap in force at its own ``t = 0``, for every segment, so the two agree on every point it projects. Zero where nothing matures and outside cover. """ if not is_active(t) or duration_mth(t) < seg_term_mth: # noqa: F821 return 0.0 if t - seg_term_mth >= t_entry(): # noqa: F821 return index_cap_at(t - seg_term_mth) # noqa: F821 return seg_index_cap_init(seg_term_mth - t) # noqa: F821
[docs] def seg_return(t): """r_k for the segment maturing in month t: its own point-to-point index change. ``index_level(t) / seg_index_start(t) - 1``, the level now over the segment's start level, :func:`seg_index_start`: :func:`index_change` inlined, as no projection cell calls an engine cell (R14). Each segment carries its own index start level, which is the whole point of a monthly ladder: collapsing twelve segments into one annual segment mis-times credits and distorts mid-segment surrender values [S3]. Zero where nothing matures, in a policy's first twelve policy months, and outside cover, where ``IUL_US_S`` leaves it to every caller to guard. """ if not is_active(t) or duration_mth(t) < seg_term_mth: # noqa: F821 return 0.0 return index_level(t) / seg_index_start(t) - 1
[docs] def seg_credit_rate(t): """cr_k for the segment maturing in month t: ``max(f, min(c, p x r))``. :func:`index_credit_rate` inlined for the projection (R14): the floor ``index_floor``, the cap declared at the segment's creation, :func:`seg_index_cap`, and the participation ``index_par`` on its own return, :func:`seg_return`, bounded in ``IUL_US_S``'s order, the cap first and then the floor, so that a return that is not a number credits the cap, and a cap that is not a number the floor, in both engines alike: ``min`` and ``max`` keep their first argument unless a later one compares past it, in Python as in the C two-argument form. Cached by month, where the engine cell is keyed by floats. :func:`index_credit_pp` multiplies it by the credit base, and :func:`cred_rate_ann` reads it as the policy's credited rate. Zero where nothing matures, in a policy's first twelve policy months, and outside cover. """ if not is_active(t) or duration_mth(t) < seg_term_mth: # noqa: F821 return 0.0 return max(index_floor, min(seg_index_cap(t), index_par * seg_return(t))) # noqa: F821
[docs] def index_credit_pp(t): """The index credit added to the account value at BOM of month t. The segment born in policy month ``m = duration_mth(t) - 12`` matures now: its credit is ``IUL_US_S``'s ``index_credit`` of its creation balance net of withdrawals and loan transfers, the deductions charged to it, its own point-to-point return, the credit base convention ``seg_credit_base_conv`` and the cap declared at its creation, inlined (R14): the credited rate, :func:`seg_credit_rate`, first, then the base, the remaining balance under ``REMAINING`` and the deductions half-weighted under ``ADJ_BEGIN``, then their product, ``IUL_US_S``'s order of operations, and a convention neither code names refused after the rate, ``"invalid credit base"``, as there. The draws and deductions to date are the segment's at the end of month ``t - 1``, in slot 11; in the first month on the books, :func:`t_entry`, a segment born before the valuation date is ladder slot 12, whose draws and deductions are its ladder row's. Zero in a policy's first twelve policy months, in every month for a model point that never creates a segment, and outside cover. """ if not is_active(t): return 0.0 m = duration_mth(t) - seg_term_mth # noqa: F821 if m < 0: return 0.0 if t > t_entry(): wd = seg_wd_cum_pp(t - 1, seg_term_mth - 1) # noqa: F821 ded = seg_ded_cum_pp(t - 1, seg_term_mth - 1) # noqa: F821 else: wd = seg_wd_cum_pp_init(seg_term_mth) # noqa: F821 ded = seg_ded_cum_pp_init(seg_term_mth) # noqa: F821 init = seg_new_pp(m) - wd rate = seg_credit_rate(t) if seg_credit_base_conv == REMAINING: # noqa: F821 base = init - ded elif seg_credit_base_conv == ADJ_BEGIN: # noqa: F821 base = init - ded / 2 else: raise ValueError("invalid credit base") return rate * base
[docs] def index_credits(t): """Index credits added to account values, for the policies in force.""" return index_credit_pp(t) * pols_if(t)
[docs] def seg_roll_pp(t): """Roll^FA_t: the matured segment value rolled into the fixed account at step 2. Remaining balance plus index credit. Under the standing allocation instruction it is swept straight back into a new segment at step 7 **[std]** (spec F11); routing it through the fixed account is what makes it available to pay this month's deduction first, which is the notes' own sourcing rule. The remaining balance is the segment's at the end of month ``t - 1``, in slot 11, or, in the first month on the books, :func:`t_entry`, ladder slot 12's. Zero in a policy's first twelve policy months and outside cover. """ if not is_active(t): return 0.0 m = duration_mth(t) - seg_term_mth # noqa: F821 if m < 0: return 0.0 if t > t_entry(): prev = seg_bal_pp(t - 1, seg_term_mth - 1) # noqa: F821 else: prev = seg_bal_pp_init(seg_term_mth) # noqa: F821 return prev + index_credit_pp(t)
[docs] def fa_pp_at(t, timing): """FA: the fixed (holding) account balance at an intra-month point of month t. The notes' recursion ``FA_{t+1} = [FA_t + NP_t - MD^FA - W^FA - B^FA - Sweep + Roll^FA] x (1+i_fix)^(1/12)`` unrolled, with ``timing`` naming the point just before each event: ``BEF_PREM`` The opening balance, the notes' ``FA_t``: the closing balance of the previous month, formed here from month ``t - 1``'s own opening balance and events, the same operations in the same order as :func:`fa_pp`, so that the chain back to the first month on the books is one cell a month. In that month, :func:`t_entry`, it is :func:`fa_pp_init`, the fixed account the point carries into the valuation month, 0 at issue (``FA(0) = 0``). ``IUL_US_S`` opens an in-force point at the account value less the loan here, everything outside the collateral in the fixed account. Zero outside cover. ``BEF_CREDIT`` After the net premium, before the maturing segment rolls in. ``BEF_WD`` After the roll, before the withdrawal and any new loan collateral. ``BEF_FEE`` After the draw, before the monthly deduction. ``BEF_SWEEP`` After the deduction, before the sweep. This is the balance the sweep takes ``w_ix`` of. ``BEF_INV`` After the sweep, before interest. Interest is credited on this balance; reversing the two overstates the account value by about one month's interest on the deduction, every month. The balance may run below zero: no policy is terminated for insufficiency, and the fixed account carries whatever the segments cannot (:func:`draw_from_fa_pp`). """ if timing == BEF_PREM: # noqa: F821 if not is_active(t): return 0.0 if t == t_entry(): return fa_pp_init() bef = fa_pp_at(t - 1, BEF_PREM) + prem_to_av_pp(t - 1) # noqa: F821 bef = bef + seg_roll_pp(t - 1) bef = bef - draw_from_fa_pp(t - 1) bef = bef - mth_deduction_from_fa_pp(t - 1) bef = bef - sweep_pp(t - 1) return bef * (1 + inv_return_mth(t - 1)) elif timing == BEF_CREDIT: # noqa: F821 return fa_pp_at(t, BEF_PREM) + prem_to_av_pp(t) # noqa: F821 elif timing == BEF_WD: # noqa: F821 return fa_pp_at(t, BEF_CREDIT) + seg_roll_pp(t) # noqa: F821 elif timing == BEF_FEE: # noqa: F821 return fa_pp_at(t, BEF_WD) - draw_from_fa_pp(t) # noqa: F821 elif timing == BEF_SWEEP: # noqa: F821 return fa_pp_at(t, BEF_FEE) - mth_deduction_from_fa_pp(t) # noqa: F821 elif timing == BEF_INV: # noqa: F821 return fa_pp_at(t, BEF_SWEEP) - sweep_pp(t) # noqa: F821 else: raise ValueError("invalid timing")
[docs] def fa_pp(t): """FA_{t+1}: the fixed (holding) account balance at the end of month t. A closing balance: the post-sweep balance plus one month's interest at the fixed-account rate. The opening balance of the month, :func:`fa_pp_init` in the first month on the books, is ``fa_pp_at(t, BEF_PREM)``, which forms this cell's value at ``t - 1`` itself rather than calling for it. Zero outside cover. """ return fa_pp_at(t, BEF_INV) * (1 + inv_return_mth(t)) # noqa: F821
[docs] def lca_pp_at(t, timing): """LCA: the loan collateral account at an intra-month point of month t. ``BEF_PREM`` is the opening balance, the notes' ``LCA_t``: the closing balance of the previous month, formed here from month ``t - 1``'s own opening balance and new loan, the same operations in the same order as :func:`lca_pp`, so that the chain is one cell a month; in the first month on the books, :func:`t_entry`, it is :func:`lca_pp_init`, the collateral the point carries into the valuation month, 0 at issue. ``IUL_US_S`` sets ``LCA(0)`` equal to ``loan_bal_init()`` **[std]**, which the collateral parts from once interest accrues. ``BEF_INV`` adds the collateral for any new loan taken at step 3, which is the balance one month's interest is credited on. Zero outside cover. """ if timing == BEF_PREM: # noqa: F821 if not is_active(t): return 0.0 if t == t_entry(): return lca_pp_init() return ((lca_pp_at(t - 1, BEF_PREM) + loan_new_pp(t - 1)) # noqa: F821 * (1 + loan_credit_rate_mth(t - 1))) elif timing == BEF_INV: # noqa: F821 return lca_pp_at(t, BEF_PREM) + loan_new_pp(t) # noqa: F821 else: raise ValueError("invalid timing")
[docs] def lca_pp(t): """LCA_{t+1}: the loan collateral account at the end of month t. Standard loans move loaned value out of the fixed account and the segments into a collateral account credited at :func:`loan_credit_rate_ann` while the loan itself accrues at the charged rate; the collateral remains part of the account value, so a loan advance does not reduce ``AV`` -- it reduces the cash surrender value through ``- L_t``. A closing balance; the opening value, :func:`lca_pp_init` in the first month on the books, is ``lca_pp_at(t, BEF_PREM)``. Zero outside cover. """ return lca_pp_at(t, BEF_INV) * (1 + loan_credit_rate_mth(t)) # noqa: F821
[docs] def loan_bal_pp(t): """L_{t+1}: the policy loan balance at the end of month t. ``L_{t+1} = (L_t + B_t) (1 + i_L^c)^(1/12)``, the notes' own recursion: new loans from step 3 are added to principal and the whole balance accrues at the charged rate. The opening balance ``L_t`` is the previous month's, and in the first month on the books, :func:`t_entry`, :func:`loan_bal_init`, the loan the point carries into the valuation month, 0 at issue. Repayments are not modeled -- the notes give no repayment pattern. Zero outside cover. """ if not is_active(t): return 0.0 opening = loan_bal_init() if t == t_entry() else loan_bal_pp(t - 1) return (opening + loan_new_pp(t)) * (1 + loan_rate_mth())
[docs] def inv_income_pp(t): """Interest credited to the account value per policy at EOM of month t. The post-sweep fixed-account balance at the fixed-account monthly rate plus the loan collateral account at the collateral credited rate. **Segments contribute nothing**: they earn no interim interest under a 0% floor design [S2], and their whole return arrives as :func:`index_credit_pp` at maturity. Keeping the two apart is what stops the floor being confused with an in-segment guarantee, which the notes list among the pitfalls. """ return (fa_pp_at(t, BEF_INV) * inv_return_mth(t) # noqa: F821 + lca_pp_at(t, BEF_INV) * loan_credit_rate_mth(t)) # noqa: F821
[docs] def inv_income(t): """Interest credited to account values, for the policies in force. Decrements fall after the credit, so every policy in force at BOM earns a full month's interest. """ return inv_income_pp(t) * pols_if(t)
[docs] def av_pp_at(t, timing): """AV: the account value per policy at an intra-month point of month t. The account value is the fixed account plus every live segment plus the loan collateral account; ``timing`` names the point just before each BOM event: ``BEF_PREM`` Before the premium: the opening balance, the notes' ``AV_t`` -- the closing balance of the previous month, formed here from month ``t - 1``'s own opening balance and events, the same operations in the same order as :func:`av_pp`, so that the chain is one cell a month. In the first month on the books, :func:`t_entry`, a point in force opens from its parts, :func:`fa_pp_init` plus :func:`lca_pp_init` plus the ladder's balances, :func:`seg_bal_pp_init`, slot by slot, summed in the compensated loop :func:`seg_bal_active_pp` sums in, so that an extract carried to the cent opens one account, its parts' sum, which :func:`check_av_components` then holds; any other point opens from :func:`av_pp_init`, 0 at issue. It is also defined in the month after the frame, ``t = proj_len()``, where it is the account value the survivors of the last month carry, which :func:`check_av_roll_fwd` reads. Zero before issue. ``BEF_CREDIT`` After the net premium, before the maturing segment's index credit. Zero outside cover, and so is every later timing. ``BEF_WD`` After the index credit, before the withdrawal. The roll of the matured segment into the fixed account is internal and does not change this total. ``BEF_FEE`` After the withdrawal, before the monthly deduction. This is the notes' ``AV'_t``, the balance the death benefit, the corridor test and the net amount at risk are all measured against. A new loan does not change it: the collateral moves within the account value. ``BEF_INV`` After the monthly deduction, before interest. The end-of-month balance, the notes' ``AV_{t+1}``, is :func:`av_pp`, and :func:`check_av_components` asserts that it still equals the sum of its three parts. """ if timing == BEF_PREM: # noqa: F821 if not 0 <= duration_mth(t) <= maturity_mth(): return 0.0 if t == t_entry(): if duration_mth_init() <= 0: return av_pp_init() s = fa_pp_init() c = 0.0 for k in range(min(seg_term_mth, duration_mth_init()) + 1): # noqa: F821 x = lca_pp_init() if k == 0 else seg_bal_pp_init(k) u = s + x if abs(s) >= abs(x): c = c + ((s - u) + x) else: c = c + ((x - u) + s) s = u if c != 0.0 and abs(c) <= 1.7976931348623157e308: s = s + c return s av = (av_pp_at(t - 1, BEF_PREM) + prem_to_av_pp(t - 1) # noqa: F821 + index_credit_pp(t - 1) - wd_pp(t - 1) - mth_deduction_pp(t - 1)) return av + inv_income_pp(t - 1) elif timing == BEF_CREDIT: # noqa: F821 if not is_active(t): return 0.0 return av_pp_at(t, BEF_PREM) + prem_to_av_pp(t) # noqa: F821 elif timing == BEF_WD: # noqa: F821 return av_pp_at(t, BEF_CREDIT) + index_credit_pp(t) # noqa: F821 elif timing == BEF_FEE: # noqa: F821 return av_pp_at(t, BEF_WD) - wd_pp(t) # noqa: F821 elif timing == BEF_INV: # noqa: F821 return av_pp_at(t, BEF_FEE) - mth_deduction_pp(t) # noqa: F821 else: raise ValueError("invalid timing")
[docs] def av_pp(t): """AV_{t+1}: the account value per policy at the end of month t. A closing balance: the post-deduction balance plus one month's interest. The opening balance, :func:`av_pp_init` in the first month on the books, is ``av_pp_at(t, BEF_PREM)``, which forms this cell's value at ``t - 1`` itself. Interest is credited on the *post-deduction* balance, as on the universal life chassis; the index credit is not part of it -- that arrives at BOM when a segment matures. Zero outside cover. """ return av_pp_at(t, BEF_INV) + inv_income_pp(t) # noqa: F821
[docs] def av_at(t, timing): """Account value in force at an intra-month point of month t. :func:`av_pp_at` times the number of policies in force, which is constant through the month because decrements are end-of-month events. ``timing`` takes the same values as :func:`av_pp_at`, plus ``EOM`` for the closing balance before decrements. At ``t = proj_len()``, ``av_at(t, BEF_PREM)`` is the account value the survivors of the last month carry, which :func:`check_av_roll_fwd` reads. """ if timing == EOM: # noqa: F821 return av_pp(t) * pols_if(t) return av_pp_at(t, timing) * pols_if(t)
[docs] def av_change(t): """Change in the account value in force over month t. ``av_at(t + 1, BEF_PREM) - av_at(t, BEF_PREM)``, following ``CashValue_SE``. Zero outside cover, before ``t + 1`` is read, so that nothing reads a month past ``t = proj_len()``; there the change would otherwise be minus the account value the survivors of the last month carry. """ if not is_active(t): return 0.0 return av_at(t + 1, BEF_PREM) - av_at(t, BEF_PREM) # noqa: F821
[docs] def surr_charge_rate(t): """SC per $1,000 of initial face in month t **[std]** scale (F17). ``max(0, sc_init - (sc_init / runoff_years) x m / 12)`` where ``m`` is the notes' own month index ``duration_mth(t) + 1`` -- the current month counts. With the shipped schedule of $25.00 per $1,000 running off over 10 years this is $24.79 in the issue month, declining linearly to zero in the last month of policy year 10. The ten-year period is sourced [S1][S5][S7]; the dollar scale is not public and is a placeholder of realistic magnitude. The schedule's two values are read once a point by :func:`surr_charge_rate_max` and :func:`surr_charge_runoff_years`, which ask ``Data`` to check the table first; the floor keeps ``IUL_US_S``'s order, ``max(0.0, ...)``, the bound first. Zero outside cover, and where the point carries no schedule. """ if not is_active(t) or not has_surr_charge(): return 0.0 init = surr_charge_rate_max() yrs = surr_charge_runoff_years() m = duration_mth(t) + 1 return max(0.0, init - (init / yrs) * (m / 12))
[docs] def surr_charge_pp(t): """SC_t: the surrender charge scheduled per policy in month t. Quoted on the **initial** face amount, because face decreases do not reduce the surrender charge [S3]. This is the schedule, not the amount collected: see :func:`surr_charge`. """ return surr_charge_rate(t) * sum_assured() / 1000
[docs] def csv_pp(t): """``AV_t - SC_t``, floored at zero: the cash value before the loan is netted. The floor is **[std]**: the notes write the cash surrender value without one, but a negative value would be a payment *from* the policyholder. In the early policy years the scheduled surrender charge exceeds the account value and the floor binds, so the charge actually collected is the whole account value. The notes' own ``CSV_t`` -- which already nets the loan -- is :func:`ncsv_pp`. """ return max(0.0, av_pp(t) - surr_charge_pp(t))
[docs] def ncsv_pp(t): """CSV_t = AV_t - SC_t - L_t: the cash surrender value, floored at zero. This is what a surrendering policyholder is paid, and the notes' surrender outflow. """ return max(0.0, csv_pp(t) - loan_bal_pp(t))
[docs] def surr_charge(t): """Surrender charge actually collected from the policies lapsing in month t. ``(AV_t - csv_pp(t)) x pols_lapse(t)``, so it is capped by the account value where the :func:`csv_pp` floor binds. Insurer income, and part of :func:`margin_expense`. """ return (av_pp(t) - csv_pp(t)) * pols_lapse(t)
[docs] def cum_prem_pp(t): """Cumulative premiums less withdrawals: the base of the GPT and 7-pay tests. The value at the end of month ``t``, including month ``t``'s own premium and withdrawal. It opens in the first month on the books, :func:`t_entry`, from :func:`cum_prem_init`, the premiums less withdrawals paid before the valuation date on a point in force and 0 at issue, so the GPT and 7-pay flags of a point in force count every premium since issue. ``IUL_US_S`` opens it at 0 on any point, the notes giving no opening accumulator **[std]**. The statutory "less a portion of withdrawals" is taken as the whole withdrawal **[std]**. Zero outside cover. """ if not is_active(t): return 0.0 opening = cum_prem_pp(t - 1) if t > t_entry() else cum_prem_init() return opening + premium_pp(t) - wd_pp(t)
[docs] def cum_prem_net_pp(t): """CumP_{t+1}: cumulative premiums less withdrawals **and loans**, the no-lapse base. The notes define the no-lapse accumulator this way and the guideline premium accumulator differently; :func:`cum_prem_pp` is the other one. Using one for the other quietly changes both answers. The value at the end of month ``t``, opening in the first month on the books, :func:`t_entry`, from :func:`cum_prem_net_init`, the accumulator the point carries into the valuation month, 0 at issue. ``IUL_US_S`` opens it at 0 on any point, which on a point in force would fail the no-lapse test against a minimum premium counted from issue. Zero outside cover. """ if not is_active(t): return 0.0 opening = cum_prem_net_pp(t - 1) if t > t_entry() else cum_prem_net_init() return opening + premium_pp(t) - wd_pp(t) - loan_new_pp(t)
[docs] def nlg_period_years(): """The length of the no-lapse period in policy years, by issue age [S3] (spec F6). 0-45: 20 years; 46-60: to attained age 65; 61+: 5 years. Comparators differ -- another carrier gives 20 years for issue ages 0-55, ``75 - issue age`` for 56-69, 5 years for 70+ [S5] -- and the structure above [S3] is the one the baseline follows. """ x = age_at_entry() if x <= 45: return 20 elif x <= 60: return max(0, 65 - x) return 5
[docs] def mnlp_pp_mth(): """The minimum monthly no-lapse premium per policy [S3]. ``mnlp_rate x F / 1000 / 12``: the annual rate per $1,000 of face spread evenly over the year. """ return mnlp_rate() * sum_assured() / 1000 / 12
[docs] def cum_mnlp_pp(t): """CumMNLP_{t+1}: the cumulative minimum no-lapse premium through month t. ``mnlp_pp_mth() x (duration_mth(t) + 1)``: a closed form on the **policy** clock, every month from issue counted, so a point in force needs no opening value for it. Zero outside cover. """ if not is_active(t): return 0.0 return mnlp_pp_mth() * (duration_mth(t) + 1)
[docs] def nlg_test_ok(t): """The cumulative-premium no-lapse test: ``CumP_t >= CumMNLP_t`` [S3][S4]. False outside cover. """ if not is_active(t): return False return cum_prem_net_pp(t) >= cum_mnlp_pp(t)
[docs] def nlg_in_effect(t): """Whether the no-lapse guarantee is in effect: inside the period and test passing. While it is, the policy cannot lapse for insufficiency even with no cash surrender value [S3][S4], which is why :func:`lapse_rate` suppresses voluntary lapse in that state as well **[std]**. The period counts policy years, from issue. False outside cover, before the policy year is compared. """ if not is_active(t): return False return policy_year(t) <= nlg_period_years() and nlg_test_ok(t)
[docs] def nlg_expiry_shock(t): """Whether the 25% no-lapse-expiry shock lapse applies in month t **[std]**. The notes apply a 25% shock lapse to *underfunded* policies on no-lapse expiry; "underfunded" is taken as a non-positive cash surrender value **[std]**, and the shock is confined to the first policy year after the no-lapse period ends. False outside cover, before the policy year is compared. """ if not is_active(t): return False return policy_year(t) == nlg_period_years() + 1 and ncsv_pp(t) <= 0
[docs] def is_shortfall(t): """The grace trigger: the cash surrender value cannot cover the monthly deduction. ``AV'_t - SC_t - L_t < MD_t`` -- with ``L_t`` the loan balance at the *start* of the month, the previous month's :func:`loan_bal_pp`, or, in the first month on the books, :func:`t_entry`, :func:`loan_bal_init` -- **and** the no-lapse test fails [S3][S4]. A diagnostic. The grace and lapse-for-insufficiency cascade (61 days, modeled as lapse at ``t + 2`` months if unfunded **[std]**) is **not implemented**: the notes leave the in-grace account value treatment and the cash flow of a cure payment undetermined, so no policy is terminated for insufficiency here. False outside cover. """ if not is_active(t): return False loan_opening = loan_bal_init() if t == t_entry() else loan_bal_pp(t - 1) csv = av_pp_at(t, BEF_FEE) - surr_charge_pp(t) - loan_opening # noqa: F821 return csv < mth_deduction_pp(t) and not nlg_in_effect(t)
[docs] def gpt_limit(t): """The guideline premium limit, ``max(GSP, GLP x policy years elapsed)`` [R4]. Zero outside cover, where the policy year is not the policy's. """ if not is_active(t): return 0.0 return max(gsp(), glp() * policy_year(t))
[docs] def gpt_ok(t): """Whether cumulative premium is still inside the guideline premium limit. A compliance side-calculation with no cash flow of its own: a refused premium simply never enters the model. False outside cover. """ if not is_active(t): return False return cum_prem_pp(t) <= gpt_limit(t)
[docs] def seven_pay_limit(t): """The 7-pay limit, ``seven_pay_prem x min(7, policy years elapsed)`` [R5]. Zero outside cover, where the policy year is not the policy's. """ if not is_active(t): return 0.0 return seven_pay_prem() * min(7, policy_year(t))
[docs] def is_mec(t): """Whether the 7-pay test has failed by month t -- once true, true for good [R5]. ``CumPrem(t) > 7-pay limit`` in any of the first seven policy years, **latched**: the flag stays set for the rest of the projection. ``IUL_US_S``'s flag is the in-year test alone, which stops applying in policy year 8 and so would switch itself off exactly when the failure becomes permanent; under IRC 7702A a contract that fails the test is a modified endowment contract for good, so this model latches it, as ``UL_US_S`` does. The in-year test comes first in every month, the first on the books included, so a policy that fails it in the valuation month is a MEC from then on. Only then does the latch look back: to month ``t - 1``, or, in the first month on the books, :func:`t_entry`, to :func:`is_mec_init`, so a policy that failed the test before the valuation date stays a MEC, even in a year where the in-year test no longer applies. False outside cover. A flag, not a cash flow: MEC status changes policyholder taxation, not insurer liability cash flows. """ if not is_active(t): return False if policy_year(t) <= 7 and cum_prem_pp(t) > seven_pay_limit(t): return True return is_mec(t - 1) if t > t_entry() else is_mec_init()
[docs] def class_factor(): """The underwriting-class multiplier on the base mortality table **[std]**. ``Data.class_factor`` at the point: the ``factor`` of the point's ``rate_class`` in *class_factor_table.csv*, joined once for the table after ``data.class_count()`` has checked its classes and factors, so that no projection cell reads the table or the class: a blank factor would otherwise reach :func:`mort_rate` as a missing value, which its cap keeps missing. A class the table has no row for is refused by ``Data``, naming every such point, at the first read, where ``IUL_US_S`` raises pandas' ``KeyError`` in every point's first month in cover. """ return float(data.class_factor()[idx]) # noqa: F821
[docs] def mort_rate(t): """The annual best-estimate mortality rate in month t. Base table times :func:`class_factor` times the A/E factor, 100% in the base run **[std]** with no mortality improvement. The notes recommend 2015 VBT sex/smoker-distinct ANB validated against ILEC 2012-2019 [REG-R18][REG-R19]; those tables are licensed, so the shipped table is a small illustrative one **[std]**. Ages beyond the table take its last row, where the rate is 1.0; the base rate is read at the attained age of month t by :func:`mort_rate_base_at`. The product is capped at 1, written ``min(q, 1.0)``, as ``IUL_US_S``'s is: a class factor above 1 carries the oldest ages' rates past 1, where the monthly rate ``1 - (1 - q)^(1/12)`` has no real value, and with the bound second a missing input, a NaN, stays NaN, where ``min(1.0, q)`` would read it as 1. On every shipped point the product reaches 1.0, at attained age 119, and never passes it, so the cap changes no shipped number. ``Data`` refuses a blank rate or class factor as it reads the tables (``data.mort_age_last()``, ``data.class_count()``), before any rate is read. Zero outside cover, before the table is read. """ if not is_active(t): return 0.0 q = mort_rate_base_at(age(t)) * class_factor() * mort_ae_factor # noqa: F821 return min(q, 1.0)
[docs] def mort_rate_base_at(a): """The base table's annual mortality rate at attained age a: the table's one reader. From *mort_table.csv*, before the class factor and the A/E factor: ``Data.mort_table_array()`` at the age, the table padded from age 0, so that the age is the index. Ages outside the table take its nearest row, which above it is the rate of 1.0 at age 120: the first and last ages ``data.mort_age_first()`` and ``data.mort_age_last()`` give, which they read from the table's key column once the keys and the rates are checked, before any rate is read, the last first, as :func:`corridor_factor_at` asks, and which keep the read off the padding. Keyed by the attained age, so the table is read once an age rather than once a month; :func:`mort_rate` calls it inside cover only. """ last = data.mort_age_last() # noqa: F821 a = min(max(a, data.mort_age_first()), last) # noqa: F821 return float(data.mort_table_array()[a]) # noqa: F821
[docs] def mort_rate_mth(t): """q^d_t: the monthly mortality rate, ``1 - (1 - q)^(1/12)`` **[std]** conversion.""" return 1 - (1 - mort_rate(t)) ** (1 / 12)
[docs] def lapse_rate_base(t): """The base annual lapse rate by policy year **[std]**. 6% in policy years 1-10, 4% thereafter, read from *lapse_table.csv* at the policy year of month t by :func:`lapse_rate_base_py`, where policy years beyond the table take its last row. The levels are placeholders to be calibrated to the LIMRA/SOA persistency studies [REG-R20][REG-R21], whose detailed tables are behind a paid package. Zero outside cover, before the table is read. """ return lapse_rate_base_py(policy_year(t)) if is_active(t) else 0.0
[docs] def lapse_rate_base_py(y): """The base annual lapse rate in policy year y, from *lapse_table.csv*: its one reader. ``Data.lapse_rate_array()`` at the year, the table padded from year 0, so that the year is the index. Policy years beyond the table take its last row, the last year ``data.lapse_last_year()`` gives, which it reads from the table's key column once it has checked the keys and the rates, before any rate is read, and a year below 1, where ``IUL_US_S``'s lookup raised ``KeyError``, is refused, naming the point and the year. Keyed by the contractual policy year, so the table is read once a policy year rather than once a month; :func:`lapse_rate_base` calls it inside cover only. """ last = data.lapse_last_year() # noqa: F821 if y < 1: raise ValueError(f"point_id {point_id()}: lapse_table.csv has no rate for policy " f"year {y}") return float(data.lapse_rate_array()[min(y, last)]) # noqa: F821
[docs] def lapse_shock_year(): """The policy year of the surrender-charge-expiry lapse spike. The first policy year with no surrender charge -- the run-off length plus one, which is 11 for the shipped ten-year schedule -- derived from the schedule's :func:`surr_charge_runoff_years` rather than hard-coded, so a different schedule moves the spike with it. Zero when the model point carries no surrender charge, which no policy year in cover can equal. The valuation clock reaches policy year 0 in the twelve months before issue, which is why :func:`lapse_rate_sc_mult` asks :func:`is_active` first. """ if not has_surr_charge(): return 0 return int(surr_charge_runoff_years()) + 1
[docs] def lapse_rate_sc_mult(t): """The surrender-charge-expiry spike multiplier, 2.0 in policy year 11 **[std]**. The ten-year surrender charge period [S1][S5][S7] creates a cliff in surrender economics; the size of the spike is a shape assumption, and UL lapse and surrender experience by duration is available in [REG-R21] for calibration. 1.0 outside cover, before the policy year is compared: in the twelve months before issue the valuation clock reaches policy year 0, the shock year :func:`lapse_shock_year` gives a point with no surrender charge. """ if not is_active(t): return 1.0 return lapse_shock_mult if policy_year(t) == lapse_shock_year() else 1.0 # noqa: F821
[docs] def cred_rate_ann(t): """r_cred,t: the policy's trailing credited rate, driving dynamic lapse **[std]**. The credited rate of the segment that matured this month once the ladder is running, from policy month 12 on, :func:`seg_credit_rate`, at the cap declared at its creation; and the fixed-account rate before that or when nothing is allocated to the indexed account. The notes say only "the policy's trailing credited rate"; this is the reading the model uses. The ladder runs from the policy's own twelfth month, so the test is on the **policy** clock, ``duration_mth(t)``, where ``IUL_US_S``'s compares ``t`` itself, its frame's month, which is the same month only on a point issued at its frame's start. A segment holding nothing still has a start level and a cap, so this reads them in every month the ladder runs. Zero outside cover. """ if not is_active(t): return 0.0 if index_alloc_rate() <= 0 or duration_mth(t) < seg_term_mth: # noqa: F821 return fixed_rate_ann(t) return seg_credit_rate(t)
[docs] def comp_rate_ann(t): """r_alt: the competitor / market alternative rate **[std]**. The base deterministic run sets it equal to the trailing credited rate, so :func:`lapse_rate_dyn_mult` is exactly 1. Override this cell, before the model computes anything, to switch dynamic lapse on; that is a formula override, which only modelx can make. The rationale the notes give is real: caps are non-guaranteed elements and uncompetitive re-declarations -- caps on one product fell from 13.75% to 12.00% between two print dates [S3][S4] -- plausibly drive excess lapse. """ return cred_rate_ann(t)
[docs] def lapse_rate_dyn_mult(t): """The dynamic lapse multiplier **[std]**. ``min(2.0, max(0.5, 1 + 3.0 x (r_alt - r_cred,t)))``: a competitive credited rate halves lapse at the floor and an uncompetitive one doubles it at the cap. Equal to 1 throughout the base run. The bounds keep ``IUL_US_S``'s order, written first. 1.0 outside cover, the neutral multiplier. """ if not is_active(t): return 1.0 raw = 1 + lapse_dyn_slope * (comp_rate_ann(t) - cred_rate_ann(t)) # noqa: F821 return min(lapse_dyn_cap, max(lapse_dyn_floor, raw)) # noqa: F821
[docs] def lapse_rate(t): """The total annual lapse rate **[std]**. Base rate times the surrender-charge-expiry spike times the dynamic multiplier, with two no-lapse-guarantee overrides the notes specify: * while the guarantee is in effect and the cash surrender value is non-positive, lapse is **suppressed** -- policyholders paying no-lapse-premium-level premiums persist; * in the first policy year after the no-lapse period ends, an underfunded policy takes a 25% shock lapse. ``lapse_rate_cap`` is 1.0: these notes give no cap, unlike the universal life chassis, so the Reference is present for symmetry and inert at its shipped value. The shock lapse is returned before the cap, as ``IUL_US_S`` returns it, so an ``nlg_shock_lapse`` past 1 is a rate past 1, whose monthly rate has no real value. Zero outside cover. """ if not is_active(t): return 0.0 if nlg_in_effect(t) and ncsv_pp(t) <= 0: return 0.0 if nlg_expiry_shock(t): return nlg_shock_lapse # noqa: F821 rate = lapse_rate_base(t) * lapse_rate_sc_mult(t) * lapse_rate_dyn_mult(t) return min(lapse_rate_cap, rate) # noqa: F821
[docs] def lapse_rate_mth(t): """q^w_t: the monthly lapse rate, ``1 - (1 - w)^(1/12)`` **[std]** conversion.""" return 1 - (1 - lapse_rate(t)) ** (1 / 12)
[docs] def pols_if(t): """l_t: the number of policies in force at the beginning of month t, row t's weight. ``pols_if_at(t, BEF_DECR)``, the notes' ``l_t``: the count carried in from month t - 1 plus month t's new business, before month t's decrements. Decrements are end-of-month events, so the number in force is constant through the month and every BOM cash flow is weighted by it. On a point issued at ``t = 0`` it is exactly ``IUL_US_S``'s ``pols_if``. A point in force at the valuation date opens with :func:`pols_if_init`, and one issued at or after it with its issued count in the issue month. Zero before issue. At ``t = proj_len()``, the month after the frame, it is the survivors of the last month, which the roll-forwards read. It is ``basiclife.BasicTerm_SE``'s ``BEF_DECR`` count, not its ``pols_if``, which is the count before maturity. """ return pols_if_at(t, BEF_DECR) # noqa: F821
[docs] def pols_if_at(t, timing): """Number of policies in force at a point of month t, by ``timing``. The three timings ``IUL_US_S``'s cell names: ``BEF_NB`` The count carried in from month t - 1, before month t's new business: month t - 1's ``BEF_DECR`` count less its deaths and lapses, death applied before lapse, in ``IUL_US_S``'s order. In the first month on the books, :func:`t_entry`, it is :func:`pols_if_init`, the count in force at the valuation date (0 for a point issued at or after it), and the recursion reads no earlier month. It is also defined in the month after the frame, ``t = proj_len()``, where it is the survivors of the last month: the projection ends at an age horizon, not at an event of the contract, so they are kept rather than matured. Zero before issue. ``BEF_DECR`` ``l_t``: ``BEF_NB`` plus :func:`pols_new_biz`, before any decrement; the same number as :func:`pols_if`, and the weight on that month's cash flows. ``BEF_MAT`` Before any maturity: ``IUL_US_S``'s meaning, the ``BEF_DECR`` count, which its cell gives for this timing. The contract has no maturity in the frame, so nothing matures and no event of the month separates the two. ``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. ``BEF_NB`` forms month t - 1's ``BEF_DECR`` count itself -- its own value at ``t - 1`` plus that month's :func:`pols_new_biz` -- and takes its deaths and lapses from the month's rates, as :func:`pols_death` and :func:`pols_lapse` do, rather than calling for any of them. So the chain of calls back to :func:`t_entry` is one cell a month, as ``IUL_US_S``'s :func:`pols_if` chain was: a compiled model runs that chain on the C stack. ``IUL_US_S``'s cell returns :func:`pols_if` for every timing, which in the issue month counts the issued policies under all three; here ``BEF_NB`` alone counts them as new business, not yet in. Any other timing raises. """ if timing == BEF_NB: # noqa: F821 if not 0 <= duration_mth(t) <= maturity_mth(): return 0.0 if t == t_entry(): return pols_if_init() prev = pols_if_at(t - 1, BEF_NB) + pols_new_biz(t - 1) # noqa: F821 q = mort_rate_mth(t - 1) return prev - prev * q - prev * (1 - q) * lapse_rate_mth(t - 1) elif timing == BEF_DECR: # noqa: F821 return pols_if_at(t, BEF_NB) + pols_new_biz(t) # noqa: F821 elif timing == BEF_MAT: # noqa: F821 return pols_if_at(t, BEF_DECR) # noqa: F821 else: raise ValueError("invalid timing")
[docs] def pols_new_biz(t): """Number of policies issued in month t: ``policy_count()`` in the issue month. The issue month is the one with ``duration_mth(t) == 0``: ``t = 0`` for a point issued at the valuation date, ``t = k`` for one issued ``k`` months later. A point already in force at the valuation date has none. """ return policy_count() if duration_mth(t) == 0 else 0.0
[docs] def pols_death(t): """Number of deaths at the end of month t, ``pols_if(t) x q^d_t``. Zero outside cover, before any rate is read. """ return pols_if(t) * mort_rate_mth(t) if is_active(t) else 0.0
[docs] def pols_lapse(t): """Number of lapses at the end of month t. ``pols_if(t) x (1 - q^d_t) x q^w_t``: death is applied before lapse **[std]**. Zero outside cover, before any rate is read. """ if not is_active(t): return 0.0 return pols_if(t) * (1 - mort_rate_mth(t)) * lapse_rate_mth(t)
[docs] def pols_maturity(t): """Number of maturing policies: always zero. At attained age 121 the policy is described as continuing in force with no further charges [unverified] (spec F5), so the projection horizon truncates the run rather than terminating the contract. The cell is kept so the in-force roll-forward identity has the same shape as in the term and annuity models of this library, where it is not zero. The survivors of the frame's last month do not mature either: they are carried into ``t = proj_len()`` (:func:`pols_if_at`). """ return 0.0
[docs] def claim_pp(t, kind): """The claim amount per policy by ``kind``. ``DEATH`` ``DB_t - L_t``, the death benefit less policy debt. The loan is taken at its end-of-month value because decrements follow the loan accrual, which is how these notes write it. ``LAPSE`` ``CSV_t``, the cash surrender value with the surrender charge and the loan already netted -- :func:`ncsv_pp`. ``WITHDRAWAL`` ``W_t - $25 fee``: the withdrawal is gross of the fee and the insurer keeps it. This kind survives here, though :func:`claims` takes no kind, because the per-policy rule has to live somewhere; :func:`withdrawals` is its only caller. """ if kind == DEATH: # noqa: F821 return max(0.0, db_pp(t) - loan_bal_pp(t)) elif kind == LAPSE: # noqa: F821 return ncsv_pp(t) elif kind == WITHDRAWAL: # noqa: F821 return max(0.0, wd_pp(t) - wd_fee_pp(t)) else: raise ValueError("invalid kind")
[docs] def claims_from_av(t, kind): """The part of a claim released out of the account value, by ``kind``. Death and lapse both release the end-of-month account value ``AV_t``, because decrements follow the interest credit. ``MATURITY`` is zero: the contract does not mature within the projection. """ if kind == DEATH: # noqa: F821 return av_pp(t) * pols_death(t) elif kind == LAPSE: # noqa: F821 return av_pp(t) * pols_lapse(t) elif kind == MATURITY: # noqa: F821 return 0.0 else: raise ValueError("invalid kind")
[docs] def claims_over_av(t): """Death claims in excess of the account value released. ``(claim_pp(t, DEATH) - AV_t) x pols_death(t)``. The cost of insurance charge net of this is the mortality margin. """ return (claim_pp(t, DEATH) - av_pp(t)) * pols_death(t) # noqa: F821
[docs] def claims(t): """Claim outgo in month t: death and surrender claims together. :func:`claims_death` and :func:`claims_lapse`, summed left to right from ``0.0``, the total ``IUL_US_S``'s ``claims(t)`` computes with its ``kind=None`` default, ``sum`` over the two kinds: a fold of two terms from ``0.0`` is that ``sum``, the sign of a zero included, so the total is ``IUL_US_S``'s bit for bit. Death claims are weighted by :func:`pols_death` and surrenders by :func:`pols_lapse`, both end-of-month events. ``WITHDRAWAL`` is deliberately **not** in the total: a partial withdrawal is a payment on the owner's election rather than a claim, so it is the standalone cell :func:`withdrawals` and its own ``result_cf()`` column. Keeping it out of the total is what stops it being counted twice. """ return 0.0 + claims_death(t) + claims_lapse(t)
[docs] def claims_death(t): """Death claims in month t: :func:`claim_pp` at ``DEATH`` times :func:`pols_death`. ``IUL_US_S``'s ``claims(t, "DEATH")``, a cell of its own, so that each kind is a monthly cell with a C cache and :func:`claims` their total. The ``claims_death`` column of :func:`result_cf`. """ return claim_pp(t, DEATH) * pols_death(t) # noqa: F821
[docs] def claims_lapse(t): """Surrender payments in month t: :func:`claim_pp` at ``LAPSE`` times :func:`pols_lapse`. ``IUL_US_S``'s ``claims(t, "LAPSE")``, a cell of its own, as :func:`claims_death` is. The ``claims_lapse`` column of :func:`result_cf`. """ return claim_pp(t, LAPSE) * pols_lapse(t) # noqa: F821
[docs] def withdrawals(t): """Partial withdrawal payments in month t: ``(W_t - $25 fee) x l_t``. Weighted by :func:`pols_if`, because a withdrawal is taken at BOM by policies still in force -- it is not a decrement. The per-policy amount is ``claim_pp(t, WITHDRAWAL)``, so the fee-inside-``W_t`` rule is stated once; the fee itself stays with the insurer as :func:`wd_fees`. A withdrawal is not a claim, and this cell is why :func:`claims`, the death and lapse claims, holds no withdrawal. """ return claim_pp(t, WITHDRAWAL) * pols_if(t) # noqa: F821
[docs] def wd_fees(t): """Withdrawal fees retained by the insurer, for the policies in force. Taken out of the withdrawal, so this is the difference between what leaves the account value and what the policyholder receives; it appears in :func:`margin_expense`, not in :func:`claims`. """ return wd_fee_pp(t) * pols_if(t)
[docs] def net_loan_cf(t): """Net loan cash flow in month t: advances out, repayments in. A loan advance is cash the insurer pays out while the account value is unchanged -- the collateral moves inside it -- so it is a liability cash flow of its own. Repayments are not modeled: the notes give no repayment pattern. """ return -loan_new_pp(t) * pols_if(t)
[docs] def inflation_factor(t): """The expense inflation factor, ``(1 + inflation_rate)^(t // 12)``. ``inflation_rate`` is **0** in the base run: these notes give per-policy maintenance and per-issue expenses as flat placeholders with no inflation assumption, unlike the universal life chassis. The cell is kept so the chassis' shape survives and an inflation assumption can be switched on with one Reference. Switched on, it steps by year on the **valuation** clock: the years are counted from the valuation date, ``t // 12``, so the expense is in valuation-date dollars whatever the policy's age, and every point of a block steps alike, on the valuation date's anniversaries. ``IUL_US_S`` steps on the policy year, ``(1 + inflation_rate)^(y - 1)``; on a point issued at ``t = 0`` the two are the same. A function of the clock alone, so it holds its value outside cover. Acquisition is not inflated (see :func:`expenses`). """ return (1 + inflation_rate) ** (t // 12) # noqa: F821
[docs] def expenses(t): """E_t: the insurer's own expenses in month t **[std]**. ``$75`` a policy a year spread monthly, plus ``$150`` at issue. Placeholders: the notes have no public source for insurer expenses and say to calibrate to company studies. ``IUL_US_S``'s formula in its order, on the policies in force at the start of the month: in the issue month those are the policies issued, :func:`pols_new_biz`, since a point issued at or after the valuation date opens with none, so acquisition is charged per policy issued, as in ``basiclife.BasicTerm_SE``, and a point in force never bears it. On a point issued at ``t = 0`` this is ``IUL_US_S``'s charge bit for bit. Not to be confused with :func:`maint_fee`, which is the charge *against the account value* -- income, not outgo. Zero outside cover, where the count carried into ``t = proj_len()`` would otherwise bear a maintenance expense. """ if not is_active(t): return 0.0 acq = expense_acq if duration_mth(t) == 0 else 0.0 # noqa: F821 return (acq + expense_maint / 12 * inflation_factor(t)) * pols_if(t) # noqa: F821
[docs] def premium_taxes(t): """Premium tax, 2.0% of premium **[std]** placeholder.""" return premium_tax_rate * premiums(t) # noqa: F821
[docs] def margin_expense(t): """Expense margin: the charges the insurer keeps, net of its own outgo. ``load x P + withdrawal fees + maint_fee + surrender charges - expenses - premium taxes``. Follows ``CashValue_SE.margin_expense``; see :func:`check_margin` for the identity it takes part in. """ return (load_prem_rate() * premium_pp(t) * pols_if(t) + wd_fees(t) + maint_fee(t) + surr_charge(t) - expenses(t) - premium_taxes(t))
[docs] def margin_mortality(t): """Mortality margin: :func:`coi` net of :func:`claims_over_av`.""" return coi(t) - claims_over_av(t)
[docs] def net_cf(t): """CF_t: the net liability cash flow in month t, **undiscounted**. ``premiums - claims - withdrawals - expenses - premium taxes + net loan cash flows``, which is the notes' own sign convention (inflow positive) and the library-wide one. :func:`claims` is the death and surrender legs only, so :func:`withdrawals` is a term of its own here rather than part of the claim total. Policy charges -- the premium load, the monthly deduction, the surrender charge, the withdrawal fee -- are internal transfers within the account value, not cash flows; they emerge in profit as the margins. Index credits and fixed-account interest are credits to the policyholder, not insurer cash flows, so they do not appear either -- see :func:`check_margin` for how it all reconciles. Zero outside cover. """ return (premiums(t) - claims(t) - withdrawals(t) - expenses(t) - premium_taxes(t) + net_loan_cf(t))
[docs] def check_av_components(): """Check that the account value is still the sum of its three parts. Returns ``True`` when, for every month of the frame, ``av_pp(t) == fa_pp(t) + seg_bal_tot_pp(t) + lca_pp(t)`` to within ``1e-9``, relative to the larger side and 10, which is what ``IUL_US_S``'s ``math.isclose`` tests with its tolerances, ``rel_tol=1e-9`` and ``abs_tol=1e-8``. :func:`av_pp` is built from the notes' aggregate recursion while the fixed account, the segment ladder and the loan collateral account are each built from their own; this is the test that the two constructions have not drifted, and it is the strongest single check on the segment bookkeeping. On a point in force the three parts open from their own columns and the account value from their sum, so an extract carried to the cent holds it too, and ``Data`` holds the ``av_pp_init`` column to the same sum. Each month's residual is :func:`check_av_components_resid`, so a failure can be found by month; a residual that is not a number fails, and one that is not real raises, as ``IUL_US_S``'s check does. """ for t in range(proj_len()): if not abs(check_av_components_resid(t)) <= 1e-9: return False return True
[docs] def check_av_components_resid(t): """The account value components' relative residual in month t; zero everywhere. ``av_pp(t)`` less the sum of the fixed account, the live segments and the loan collateral at the end of month t, over the larger of the two in magnitude and 10: one number a month, whose magnitude is within ``1e-9`` exactly where ``math.isclose`` with ``rel_tol=1e-9`` and ``abs_tol=1e-8`` holds, ``IUL_US_S``'s test. Returned as a ``float``, so that a value that is not real raises here, as ``IUL_US_S``'s ``math.isclose`` raises on it. Zero outside cover. """ if not is_active(t): return 0.0 parts = fa_pp(t) + seg_bal_tot_pp(t) + lca_pp(t) av = av_pp(t) return float((av - parts) / max(abs(av), abs(parts), 10.0))
[docs] def check_av_roll_fwd(): """Check the account value roll-forward. Returns ``True`` when, for every month of the frame, the opening account value in force of month ``t + 1`` equals:: av_at(t, BEF_PREM) + prem_to_av(t) + index_credits(t) - withdrawals(t) - wd_fees(t) - mth_deduction(t) + inv_income(t) - claims_from_av(t, DEATH) - claims_from_av(t, LAPSE) to within ``1e-9``, relative to the larger of the two and 10, as for :func:`check_av_components`. This pins the notes' processing order: the index credit arrives at BOM when a segment matures, interest is credited on the *post-deduction* balance, decrements come after both, and the withdrawal fee leaves the account value alongside the withdrawal itself. Each month's residual is :func:`check_av_roll_fwd_resid`; a residual that is not a number fails, and one that is not real raises, as ``IUL_US_S``'s check does. In the last month the opening value of ``t + 1`` is the account value the survivors carry into ``t = proj_len()``. """ for t in range(proj_len()): if not abs(check_av_roll_fwd_resid(t)) <= 1e-9: return False return True
[docs] def check_av_roll_fwd_resid(t): """The account value roll-forward's relative residual in month t; zero everywhere. The opening account value in force of month ``t + 1`` less the roll-forward of month t that :func:`check_av_roll_fwd` sets out, over the larger of the two in magnitude and 10, and a ``float``, as :func:`check_av_components_resid` is: a monthly rate built from an annual one past 1, ``1 - (1 - q)^(1/12)``, is complex, and so is every count after it, and a complex residual's magnitude would pass. Zero outside cover, before ``t + 1`` is read, so that nothing reads a month past ``t = proj_len()``. """ if not is_active(t): return 0.0 av = (av_at(t, BEF_PREM) # noqa: F821 + prem_to_av(t) + index_credits(t) - withdrawals(t) - wd_fees(t) - mth_deduction(t) + inv_income(t) - claims_from_av(t, DEATH) # noqa: F821 - claims_from_av(t, LAPSE)) # noqa: F821 nxt = av_at(t + 1, BEF_PREM) # noqa: F821 return float((nxt - av) / max(abs(nxt), abs(av), 10.0))
[docs] def check_seg_ladder(): """Check the segment ladder bookkeeping. Returns ``True`` when, for every month of the frame, all four of the following hold: * at most ``seg_term_mth`` segments are live (:func:`check_seg_count_resid`); * every segment that matured accounted for its creation balance exactly, ``seg_new_pp(m) == seg_bal_pp(t - 1, 11) + deductions + withdrawals`` -- nothing may appear in or vanish from a segment except a deduction, a withdrawal or a loan transfer, because segments earn no interim interest (:func:`check_seg_closure_resid`); * **every live segment balance is non-negative**, to within ``1e-8`` (:func:`check_seg_bal_resid`); * **every index credit is non-negative**, to within ``1e-8`` (:func:`check_seg_credit_resid`). The last two are the 0% floor of ``cr_k = max(f, min(c, p x r))`` [S2][R1] stated as an invariant. The accounting identity above closes even on a negative balance, and :func:`seg_count` counts only positive ones, so without these two an over-sourced draw could take a segment below zero and pay a negative credit on it at maturity without any check firing -- see :func:`mth_deduction_from_seg_pp`. ``IUL_US_S``'s tests and tolerances, each month's read from a residual cell; a residual that is not a number fails each test. A segment born before the valuation date that matures in month 0 closes on its creation balance by construction, since that balance is its ladder row summed (:func:`seg_new_pp`). """ for t in range(proj_len()): if not check_seg_count_resid(t) <= 0: return False if not check_seg_credit_resid(t) >= -1e-8: return False if not check_seg_bal_resid(t) >= -1e-8: return False if not abs(check_seg_closure_resid(t)) <= 1e-9: return False return True
[docs] def check_seg_count_resid(t): """The live segments beyond ``seg_term_mth`` at the end of month t: zero or below. ``seg_count(t) - seg_term_mth`` as a ``float``, which :func:`check_seg_ladder` holds to 0 or below, ``IUL_US_S``'s ``seg_count(t) <= seg_term_mth``. Zero outside cover. """ if not is_active(t): return 0.0 return float(seg_count(t) - seg_term_mth) # noqa: F821
[docs] def check_seg_credit_resid(t): """The index credit of month t per policy, held by the ladder check to -1e-8 or more. :func:`index_credit_pp`, which :func:`check_seg_ladder` holds to ``-1e-8`` or more, ``IUL_US_S``'s tolerance. Zero outside cover, where no segment matures. """ return index_credit_pp(t)
[docs] def check_seg_bal_resid(t): """The least live segment balance at the end of month t, or 0 where none is below. The smallest of 0 and the balances of the segments born in policy months ``max(0, duration_mth(t) - 11)`` to ``duration_mth(t)``, each read at its slot, which :func:`check_seg_ladder` holds to ``-1e-8`` or more, ``IUL_US_S``'s test of each balance. A balance that is not a number, once met, is kept, so that the residual is not a number and the check fails, as ``IUL_US_S``'s does. Zero outside cover. """ if not is_active(t): return 0.0 d = duration_mth(t) low = 0.0 for m in range(max(0, d - seg_term_mth + 1), d + 1): # noqa: F821 b = seg_bal_pp(t, d - m) if low == low and not b >= low: low = b return low
[docs] def check_seg_closure_resid(t): """The closure's relative residual for the segment maturing in month t; zero. The creation balance of the segment born in policy month ``duration_mth(t) - 12``, :func:`seg_new_pp`, less its balance at the end of month ``t - 1``, in slot 11, plus the deductions and the draws charged to it, over the larger of the two in magnitude and 10, a ``float``, as :func:`check_av_components_resid` is: ``math.isclose`` with ``IUL_US_S``'s tolerances. In the first month on the books, :func:`t_entry`, a segment born before the valuation date is ladder slot 12, read from its row. Zero where nothing matures and outside cover. """ if not is_active(t): return 0.0 m = duration_mth(t) - seg_term_mth # noqa: F821 if m < 0: return 0.0 k = seg_term_mth - 1 # noqa: F821 if t > t_entry(): closed = (seg_bal_pp(t - 1, k) + seg_ded_cum_pp(t - 1, k) + seg_wd_cum_pp(t - 1, k)) else: closed = (seg_bal_pp_init(seg_term_mth) + seg_ded_cum_pp_init(seg_term_mth) + seg_wd_cum_pp_init(seg_term_mth)) # noqa: F821 new = seg_new_pp(m) return float((new - closed) / max(abs(new), abs(closed), 10.0))
[docs] def check_margin(): """Check the net cash flow against the expense and mortality margins. Returns ``True`` when, for every month of the frame:: net_cf(t) == margin_expense(t) + margin_mortality(t) + av_change(t) - inv_income(t) - index_credits(t) + min(loan_bal_pp(t), csv_pp(t)) * pols_lapse(t) + net_loan_cf(t) to within ``1e-9``, relative to the larger side and 10, as for :func:`check_av_components`; each month's residual is :func:`check_margin_resid`, and a residual that is not a number fails. The terms after the two margins are what separates a *gross liability cash flow* model from ``CashValue_SE``, whose ``net_cf`` already nets the change in account value and the investment income. ``index_credits`` joins ``inv_income`` because the indexed account's whole return arrives at maturity rather than monthly; the loan terms are the debt a surrender recovers out of the cash value, which is the whole loan while the cash value covers it and the cash value once the loan exceeds it, where :func:`ncsv_pp` pays nothing, and the advance itself. ``IUL_US_S``'s identity takes the whole loan in every month, which holds while neither the :func:`csv_pp` nor the :func:`ncsv_pp` floor binds against a policy loan, so its check fails on its point 5, whose loan overruns the cash value from policy month 383, on a projection that is right; this model states the identity as ``UL_US_SEC``, ``VUL_US_SEC`` and ``ULSG_US_SEC`` do, and on every point whose loan stays within its cash value the two agree. """ for t in range(proj_len()): if not abs(check_margin_resid(t)) <= 1e-9: return False return True
[docs] def check_margin_resid(t): """The margin identity's relative residual in month t; zero everywhere. ``net_cf(t)`` less the two margins, the change in account value, the interest and the index credits, the loan a surrender recovers and the net loan cash flow, that :func:`check_margin` sets out, over the larger of the two sides in magnitude and 10, a ``float``, as :func:`check_av_components_resid` is. Zero outside cover, before :func:`av_change` would read ``t + 1``. """ if not is_active(t): return 0.0 rhs = (margin_expense(t) + margin_mortality(t) + av_change(t) - inv_income(t) - index_credits(t) + min(loan_bal_pp(t), csv_pp(t)) * pols_lapse(t) + net_loan_cf(t)) lhs = net_cf(t) return float((lhs - rhs) / max(abs(lhs), abs(rhs), 10.0))
[docs] def result_cf(): """Result table of cashflows, a DataFrame indexed by month ``t``. One row per month ``t = 0 .. proj_len() - 1`` from the valuation date, the same month for every model point, so the frames of a block line up and sum row by row, and a point issued after the valuation date has zeros until its issue month; ``len(result_cf()) == proj_len()``. The columns are ``IUL_US_S``'s. ``pols_if`` is the number in force at the **start** of month ``t`` and is the weight on that same row's cash flows. The cash flow columns are income-positive and sum to ``net_cf``: ``premiums - claims_death - claims_lapse - withdrawals - expenses - premium_taxes + net_loan_cf``. The surrender column is ``claims_lapse``, matching the ``LAPSE`` kind that produces it, and withdrawals are their own column because they are not claims. """ ts = list(range(proj_len())) return pd.DataFrame( # noqa: F821 { "pols_if": [pols_if(t) for t in ts], "premiums": [premiums(t) for t in ts], "claims_death": [claims_death(t) for t in ts], "claims_lapse": [claims_lapse(t) for t in ts], "withdrawals": [withdrawals(t) for t in ts], "expenses": [expenses(t) for t in ts], "premium_taxes": [premium_taxes(t) for t in ts], "net_loan_cf": [net_loan_cf(t) for t in ts], "net_cf": [net_cf(t) for t in ts], }, index=pd.Index(ts, name="t"), # noqa: F821 )
[docs] def result_pols(): """Result table of policy counts and decrement rates, a DataFrame indexed by ``t``. One row per month ``t = 0 .. proj_len() - 1``, as in :func:`result_cf`. First the counts :func:`result_cf` weights its rows by, and how they move, as ``basiclife.BasicTerm_SE``'s ``result_pols`` sets them out: ``pols_if``, the count of month t; ``pols_new_biz``, the part of it issued in month t; then month t's deaths and lapses, in ``IUL_US_S``'s order, and its maturities, which are always zero. Row by row, ``pols_if`` at ``t + 1`` is ``pols_if`` less the two outflows of month t, plus the new business of month ``t + 1``. Then ``IUL_US_S``'s two monthly decrement rates, which are 0 outside cover, where the model reads no rate. """ ts = list(range(proj_len())) rows = [] for t in ts: active = is_active(t) rows.append((pols_if(t), pols_new_biz(t), pols_death(t), pols_lapse(t), pols_maturity(t), mort_rate_mth(t) if active else 0.0, lapse_rate_mth(t) if active else 0.0)) return pd.DataFrame( # noqa: F821 rows, columns=["pols_if", "pols_new_biz", "pols_death", "pols_lapse", "pols_maturity", "mort_rate_mth", "lapse_rate_mth"], index=pd.Index(ts, name="t"), # noqa: F821 )
[docs] def result_av(): """Result table of the per-policy account value roll-forward. The columns follow the notes' processing order: opening account value, net premium, the index credit of any maturing segment, the account value before the deduction, the death benefit, the net amount at risk, the cost of insurance, the monthly deduction, the post-deduction balance, the interest credited, the closing account value, and then the surrender and loan values. One row per month ``t = 0 .. proj_len() - 1`` from the valuation date, as in :func:`result_cf`; ``av_pp_bef_prem`` on row ``t`` is the opening balance and ``av_pp`` the closing one. """ ts = list(range(proj_len())) return pd.DataFrame( # noqa: F821 { "av_pp_bef_prem": [av_pp_at(t, BEF_PREM) for t in ts], # noqa: F821 "prem_to_av_pp": [prem_to_av_pp(t) for t in ts], "index_credit_pp": [index_credit_pp(t) for t in ts], "av_pp_bef_fee": [av_pp_at(t, BEF_FEE) for t in ts], # noqa: F821 "db_pp": [db_pp(t) for t in ts], "net_amt_at_risk": [net_amt_at_risk(t) for t in ts], "coi_pp": [coi_pp(t) for t in ts], "mth_deduction_pp": [mth_deduction_pp(t) for t in ts], "av_pp_bef_inv": [av_pp_at(t, BEF_INV) for t in ts], # noqa: F821 "inv_income_pp": [inv_income_pp(t) for t in ts], "av_pp": [av_pp(t) for t in ts], "surr_charge_pp": [surr_charge_pp(t) for t in ts], "ncsv_pp": [ncsv_pp(t) for t in ts], "loan_bal_pp": [loan_bal_pp(t) for t in ts], }, index=pd.Index(ts, name="t"), # noqa: F821 )
[docs] def result_seg(): """Result table of the indexed segment ladder, a DataFrame indexed by ``t``. The index level, the fixed (holding) account, the sweep that creates this month's segment, the total and count of live segments, the credit paid by the segment maturing this month and the return that produced it (0 in a policy's first twelve policy months, when nothing can mature yet). One row per month ``t = 0 .. proj_len() - 1`` from the valuation date, as in :func:`result_cf`. The index level is the path on the valuation clock, :func:`index_level`, which on a point in force differs from ``IUL_US_S``'s by a constant factor; every other column is a ratio of levels or an amount, and moves with the segments, not with the path. """ ts = list(range(proj_len())) return pd.DataFrame( # noqa: F821 { "index_level": [index_level(t) for t in ts], "fa_pp": [fa_pp(t) for t in ts], "sweep_pp": [sweep_pp(t) for t in ts], "seg_bal_tot_pp": [seg_bal_tot_pp(t) for t in ts], "seg_count": [seg_count(t) for t in ts], "index_credit_pp": [index_credit_pp(t) for t in ts], "seg_return": [seg_return(t) for t in ts], "lca_pp": [lca_pp(t) for t in ts], }, index=pd.Index(ts, name="t"), # noqa: F821 )
# --------------------------------------------------------------------------- # References data = ("Interface", ("..", "Data"), "auto") idx = 0 BEF_NB = 0 BEF_DECR = 1 BEF_MAT = 2 BEF_PREM = 3 BEF_CREDIT = 4 BEF_WD = 5 BEF_FEE = 6 BEF_SWEEP = 7 BEF_INV = 8 EOM = 9 DEATH = 0 LAPSE = 1 MATURITY = 2 WITHDRAWAL = 3 CURRENT = 0 GUARANTEED = 1 REMAINING = 0 ADJ_BEGIN = 1 issue_age_min = 0 issue_age_max = 85 basis = 0 maturity_age = 121 omega_age = 120 charges_cease_age = 121 guar_rate_ann = 0.01 fixed_rate_curr = 0.045 index_cap_curr = 0.1 index_cap_guar = 0.02 index_par = 1.0 index_floor = 0.0 index_return_ann = 0.064 index_level_init = 4500.0 seg_term_mth = 12 seg_credit_base_conv = 0 load_prem_rate_guar = 0.08 expense_pol_mth = 10.0 expense_pol_mth_guar = 15.0 expense_unit_mth_1 = 0.3 expense_unit_mth_2 = 0.0 expense_unit_mth_guar = 0.4 expense_unit_step_year = 10 coi_curr_factor = 0.65 loan_rate_ann = 0.03 loan_credit_rate_ann_1 = 0.02 loan_credit_rate_ann_2 = 0.03 loan_credit_step_year = 10 wd_fee = 25.0 prem_persistency_rate = 0.98 mort_ae_factor = 1.0 lapse_shock_mult = 2.0 lapse_dyn_slope = 3.0 lapse_dyn_cap = 2.0 lapse_dyn_floor = 0.5 lapse_rate_cap = 1.0 nlg_shock_lapse = 0.25 expense_acq = 150.0 expense_maint = 75.0 inflation_rate = 0.0 premium_tax_rate = 0.02 pd = ("Module", "pandas")