Source code for uslib.products.universal_life.UL_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:`~.UL_US_SEC` model.

The Space is parameterized by ``idx``, the position of a model point in the table and in
every :mod:`~.UL_US_SEC.Data` vector, as ``basiclife.BasicTerm_SC`` is: ``Projection[5]``
is an ItemSpace projecting the table's sixth row, model point 6, ``UL_US_S``'s in-force
point restated six months on, in force 126 months at the valuation date with its loan,
and :func:`point_id` is its label::

    >>> Projection[5].result_cf()          # one row per month from the valuation date
    >>> Projection[5].result_av()          # the account value roll-forward behind it
    >>> Projection[5].point_id()           # 6, 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, and an int set on a float Reference reads as a float
(``products/universal_life/model-sec.md``, *What it refuses*).

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:`~.UL_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:`~.UL_US_S` is rewritten where it depends on where the projection starts, where it
must answer for a month outside cover, or where it reads a table at a policy year or an
attained age; every other is :mod:`~.UL_US_S`'s own.
``products/universal_life/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, every timing and kind is an
int code (*Codes*, below), :mod:`~.UL_US_S`'s ``coi_rate_scale``, a Series, is a schedule
number, :func:`coi_schedule`, and :mod:`~.UL_US_S`'s ``claims(t, kind=None)`` is two
cells and their total.

.. rubric:: Input data

Inputs are **external files**: plain CSVs living in the model folder's parent
directory, ``products/universal_life/``, 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
``UL_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:`~.UL_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 seven assumption tables are the files :mod:`~.UL_US_S` reads,
read in place; the model point table is this model's own:

======================  ================================  ==========================
Reference (on Data)     Cells                             File
======================  ================================  ==========================
model_point_file        data.model_point_table()          model_point_table_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
prem_persistency_file   data.prem_persistency_table()     prem_persistency.csv
surr_charge_file        data.surr_charge_table()          surr_charge_table.csv
======================  ================================  ==========================

.. 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 months the policy has been in force at
time ``t``: ``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. It is the notes' ``d(t)``, and everything contractual
reads it: the surrender charge run-off, the COI, per-unit and premium persistency scales
by policy year, the corridor factor and the mortality rate by attained age, the first
withdrawal year, and the GPT and 7-pay limits. 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 3,
``UL_US_S``'s in-force cell, is in policy year 11 at attained age 45 at ``t = 0``, and
point 9, to be issued 25 months after the valuation date, is issued at ``t = 25``.

``UL_US_S`` already counts its months from the start of its own projection rather than
from issue, and opens its in-force point 3 there with its account value and its loan.
What the valuation clock adds is that ``t = 0`` is one instant for every point, that a
point may be issued after it, and that a point in force brings in what its past has left
it: the face its withdrawals have left, the year's free allowance it has used, the
premiums it has paid and its MEC latch, four more opening values than ``UL_US_S`` reads.

The economic inputs read the valuation clock: the declared rates,
:func:`crediting_rate_ann` and :func:`comp_rate_ann`, flat as shipped, and expense
inflation, ``inflation_factor(t) = (1 + inflation_rate)^(t // 12)``, ``UL_US_S``'s step
by year moved onto ``t``, so that the maintenance expense is in valuation-date dollars for
every point alike. Acquisition is charged per policy issued, in the issue month, and is
not inflated, as in ``basiclife.BasicTerm_SE``.

On a point issued at ``t = 0`` the two clocks coincide and this model computes what
:mod:`~.UL_US_S` computes: every cell the two share agrees at every argument
:mod:`~.UL_US_S` evaluates in its sweep, but for three whose meaning changed,
``pols_if_init``, now the count already in force at the valuation date, ``model_point``,
a row of another table, and ``result_pols``, which gains the month's new business, and
``coi_rate_scale``, which this model replaces with :func:`coi_schedule`. S's ``claims(t,
kind)`` is :func:`claims_death` and :func:`claims_lapse` here, and its total,
``claims(t, None)``, is :func:`claims`. That
is how :mod:`~.UL_US_S`'s goldens on its new-business points carry over, the worked
example among them, and ``tests/test_model_conventions.py`` asserts it cell by cell. On
point 3 the projection is :mod:`~.UL_US_S`'s, month for month, its expenses apart, which
are in valuation-date dollars.

The **value** state variables are closing balances at the end of month ``t``:
``av_pp(t)``, ``loan_bal_pp(t)`` and ``cum_prem_pp(t)``. ``sum_assured_at(t)`` is not a
closing balance: it is the face amount in force **during** month ``t``, after that
month's BOM withdrawal reduction -- the face that ``db_pp(t)``, ``net_amt_at_risk(t)``
and ``units(t)`` are measured on. ``wd_used_year(t)`` is the free allowance used in the
policy year before month ``t``'s withdrawal, and ``is_mec(t)`` the 7-pay latch after
month ``t``'s test. The opening values -- the notes' ``AV(t-1)``, ``L(t-1)``,
``CumPrem(t-1)`` -- are ``av_pp_at(t, BEF_PREM)``, ``loan_bal_pp_bom(t)`` and
``cum_prem_pp(t - 1)``, and at :func:`t_entry`, the first month on the books, each chain
opens from 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 six columns of its row, per policy, as the policy stands at the start of month 0,
before any month-0 event: the account value and the loan, ``UL_US_S``'s own columns
(:func:`av_pp_init`, :func:`loan_bal_init`); the face in force
(:func:`sum_assured_init`); the free withdrawal allowance already used in the policy year
under way (:func:`wd_used_year_init`); the premiums less withdrawals paid to date
(:func:`cum_prem_init`); and the MEC latch (:func:`is_mec_init`). ``UL_US_S`` takes the
last four as they stand at issue, the face at issue and nothing used, paid or failed, on
its in-force point too. For a point issued at or after the valuation date every one of
them is 0, and the issue values come from the formulas: :func:`sum_assured` for the face,
0 for the rest.

Every chain is one cell a month. ``av_pp_at(t, BEF_PREM)`` forms the previous month's
close itself, from its own value at ``t - 1`` and month ``t - 1``'s net premium,
withdrawal, fee, deduction and interest, the same sum in the same order as
``av_pp(t - 1)``, rather than calling for it, where ``UL_US_S``'s account value chain ran
through five cells a month; :func:`loan_bal_pp_bom` does the same for the loan, where
``UL_US_S``'s ran through two, and the ``BEF_NB`` timing of :func:`pols_if_at` for the
count, one cell a month as ``UL_US_S``'s :func:`pols_if` already was. The face, the year's
withdrawal usage and the cumulative premium call themselves at ``t - 1`` before anything
else, and the MEC latch does once its in-year test has run. A compiled model runs these
chains on the C stack.

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

1. amortize the surrender charge (:func:`surr_charge_rate`);
2. gross premium and its load, net premium to the account value
   (:func:`premium_pp`, :func:`prem_to_av_pp`);
3. withdrawal and withdrawal fee, and under Option A the face reduction they force
   (:func:`wd_pp`, :func:`wd_fee_pp`, :func:`sum_assured_at`) -- after which the
   account value is the notes' ``AV'(t)``, :func:`av_pp_at(t, BEF_FEE)<av_pp_at>`;
4. death benefit and the GPT corridor test (: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`);
6. the monthly deduction (:func:`mth_deduction_pp`);
7. the shortfall test (:func:`is_shortfall`);
8. end of month: one month's interest on the post-deduction balance
   (:func:`inv_income_pp`) and loan interest accrual (:func:`loan_bal_pp`);
9. end of month: decrements, 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 ``pols_if(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)``.
Partial withdrawals also fall at BOM and are weighted by ``pols_if(t)``, but they are
:func:`withdrawals`, a cash flow line of their own rather than a ``kind`` of
:func:`claim_pp`.

.. 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. ``UL_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 ``UL_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:`~.UL_US_S`'s, death before lapse.

.. rubric:: The end of the projection

The frame ends at :func:`omega_mth`, where the mortality table ends, and not at an event
of the contract, which never matures. With the shipped table -- an annual rate of 1.0 at
ages 119 and 120 -- and a class factor and an A/E of 1 or more, every life has died by
the end of the first month at attained age 119. With a preferred class, an A/E below 1,
or a table that stays below 1, lives survive the last month, and the roll-forwards read
them: :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) <= omega_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. Both equal :mod:`~.UL_US_S`'s values there
exactly. Every other cell is zero or false there, as before issue: the account value
inside the month, the loan, every charge, premium, withdrawal, 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 lapse shock's
neutral 1.0 hold values there.
And nothing reads past ``t = proj_len()``: :func:`av_change` and the two checks' residual
cells, which read ``t + 1``, are zero outside cover before they read it.

.. rubric:: Naming

Cell names follow lifelib's ``basiclife.BasicTerm_S`` and ``savings.CashValue_SE``
wherever those models have an analogue -- ``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. 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 ``omega_mth`` this model's, named for ``omega_age``, where the
projection ends, since the contract has no end of its own. A column of the opening state
is the cell it opens with ``_init`` added, in ``UL_US_S``'s spelling of the stem:
``av_pp_init`` and ``loan_bal_init`` are ``UL_US_S``'s own, ``sum_assured_init``,
``wd_used_year_init`` and ``is_mec_init`` are new, and ``cum_prem_init`` is
``ULSG_US_S``'s name for the same column. ``wd_used_year`` already says it restarts each
policy year, so its column takes no ``_ytd``. A table read at a policy year has one
reader keyed by the year, ``<cell>_py(y)``, and a table read at an attained age one keyed
by the age, ``<cell>_at(a)``; the monthly cell keeps ``UL_US_S``'s name and calls it
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`, and
the COI scale, keyed by sex, class and issue age, is numbered, :func:`coi_schedule`. A
check's residual in month t is ``<check>_resid(t)``. A text column a monthly cell
branches on is read through bool decodes, one for each value it branches on, named for
the value:
:func:`is_db_option_a` and :func:`is_db_option_b`, :func:`is_gpt`, and
:func:`is_level_premium`, :func:`is_single_premium` and :func:`is_target_premium`. No
projection cell reads text: ``Data`` decodes each column into its flags, and joins the
class factor, the COI scale and the surrender-charge schedule to the points by their text
keys, so ``UL_US_S``'s label accessors are kept for reporting alone (*Reporting cells*,
below). Each of ``UL_US_S``'s claim kinds is a cell, ``claims_<kind>(t)``, and
:func:`claims` their total, as in the family's other compiled models.

The technical notes use compact actuarial symbols instead. The mapping is:

=========================  ==============================  ==========================
Notes symbol               Cells                           Meaning
=========================  ==============================  ==========================
t                          (the ``t`` argument)            Months from the valuation date
d(t)                       duration_mth(t)                 Completed policy months at
                                                           month t, the notes' month index
y                          policy_year(t)                  Policy year, d(t) // 12 + 1
(y - 1)                    duration(t)                     Completed policy years
(none)                     point_id                        The row's label, at idx
x / issue_age              age_at_entry                    Issue age (ANB)
x + y - 1                  age(t)                          Attained age (ANB)
proj_len                   proj_len                        Months from the valuation date
                                                           to the end of the projection
(table's last age)         omega_age                       Last age of the table, 120
(projection end)           omega_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
sex                        sex                             Sex, M or F
risk_class                 rate_class                      Underwriting class, one of six
F / face_amount            sum_assured                     Initial total face amount
F(t)                       sum_assured_at(t)               Total face after reductions
(opening F)                sum_assured_init                Face in force entering month 0
U                          units(t)                        Face in $1,000 units
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
qual_test                  qual_test                       7702 test elected; GPT only
(GPT elected)              is_gpt                          Whether qual_test is GPT
premium_pattern            premium_type                    LEVEL / SINGLE / 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
premium_mode               (not modelled)                  Monthly premiums only **[std]**
planned_premium_annual     premium_pp_ann                  Planned annual premium
av_initial                 av_pp_init                      Account value entering month 0
loan_balance_initial       loan_bal_init                   Loan balance entering month 0
policy_month_offset        duration_mth_init               Completed policy months at the
                                                           valuation date; -k if issued k
                                                           months later
(none)                     policy_count                    Policies the model point
                                                           stands for
sc_layer_table             surr_charge_id                  Surrender charge schedule ID
(schedule applies)         has_surr_charge                 Whether a schedule applies
(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
guideline_single_premium   gsp                             GSP in the GPT limit
guideline_level_premium    glp                             GLP in the GPT limit
seven_pay_premium          seven_pay_prem                  7-pay premium, an input
GP(t)                      premium_pp(t)                   Gross premium per policy
pp(y)                      prem_persistency(t)             Paid/planned factor
(pp by year)               prem_persistency_py(y)          The same, keyed by policy year
pl                         load_prem_rate                  Current premium load rate
NP(t)                      prem_to_av_pp(t)                Net premium to account value
W(t)                       wd_pp(t)                        Partial withdrawal
(planned W)                wd_pp_mth                       The wd_pp column, a month's W
wf                         wd_fee_pp(t)                    Withdrawal fee ($25)
(free amount)              wd_free_pp(t)                   Free allowance still available
wd_used_year               wd_used_year(t)                 Free allowance used this year
(opening usage)            wd_used_year_init               The usage entering month 0
(face cut)                 face_reduction_pp(t)            Option A face reduction
AV(t)                      av_pp(t)                        Account value, end of month
AV(t-1)                    av_pp_at(t, BEF_PREM)           Account value, start of month
(after premium)            av_pp_at(t, BEF_WD)             Before the withdrawal
AV'(t)                     av_pp_at(t, BEF_FEE)            After premium and withdrawal
(AV'(t) floored at 0)      av_pp_db_basis(t)               The AV' that DB and NAAR use
AV'(t) - MD(t)             av_pp_at(t, BEF_INV)            After the monthly deduction
(aggregate AV)             av_at(t, timing)                Account value in force
(none)                     av_change(t)                    Change in account value
e_pol                      expense_pol_mth                 Per-policy charge
e_unit(y)                  expense_unit_mth_1/_2           Per-unit charge
rc(t)                      rider_charge_pp(t)              Rider charges (0)
(e_pol + e_unit U + rc)    maint_fee_pp(t)                 Non-COI monthly charges
MD(t)                      mth_deduction_pp(t)             Monthly deduction
(the point's scale)        coi_schedule                    Its row of the COI table
q_coi_guar(s)              coi_rate_guar(t)                Guaranteed maximum COI rate
(q_coi_guar by year)       coi_rate_guar_py(y)             The same, keyed by policy year
(last year of the scale)   coi_rate_last_year              The scale's last policy year
q_coi(s)                   coi_rate(t)                     Current COI rate
(COI charge)               coi_pp(t)                       Cost of insurance charge
NAAR(t)                    net_amt_at_risk(t)              Net amount at risk
DB(t)                      db_pp(t)                        Death benefit after corridor
cf(a)                      corridor_factor(t)              GPT corridor factor
(cf by age)                corridor_factor_at(a)           The same, keyed by age
(NAAR factor)              naar_factor                     1 + i_gm
i_guar                     guar_rate_ann                   Guaranteed annual rate
i_cr                       crediting_rate_ann(t)           Current credited annual rate
i_m                        inv_return_mth(t)               Monthly credited rate
i_gm                       guar_rate_mth                   Monthly guaranteed rate
(interest credited)        inv_income_pp(t)                Interest credited to AV
earned_rate(t)             (not modelled)                  NGE revision input, no source
L(t)                       loan_bal_pp(t)                  Loan balance, end of month
L(t-1)                     loan_bal_pp_bom(t)              Loan balance, start of month
r_L                        loan_rate_ann                   Charged loan rate
SC(t)                      surr_charge_pp(t)               Surrender charge
(SC per $1,000)            surr_charge_rate(t)             Surrender charge rate
CSV(t)                     csv_pp(t)                       Cash surrender value
NCSV(t)                    ncsv_pp(t)                      Net cash surrender value
(SC retained)              surr_charge(t)                  Surrender charge collected
CumPrem(t)                 cum_prem_pp(t)                  Cumulative premiums
(opening CumPrem)          cum_prem_init                   Premiums less withdrawals
                                                           before the valuation date
(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 flag, latched
(opening MEC flag)         is_mec_init                     The latch entering month 0
(grace trigger)            is_shortfall(t)                 AV' - L < MD
grace_flag(t)              (not modelled)                  In-grace state; see below
(cure payment)             cure_premium_pp(t)              3 x MD plus load
q_m(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
w_base(y)                  lapse_rate_base(t)              Base annual lapse rate
(w_base by year)           lapse_rate_base_py(y)           The same, keyed by policy year
M_sc                       lapse_rate_sc_mult(t)           SC-expiry lapse shock
(shock year)               lapse_shock_year                Policy year of the shock
M_rate(t)                  lapse_rate_dyn_mult(t)          Dynamic lapse multiplier
r_comp(t)                  comp_rate_ann(t)                Competitor new-money rate
w_annual(y,t)              lapse_rate(t)                   Total annual lapse rate
w_m(t)                     lapse_rate_mth(t)               Monthly lapse rate
l(t)                       pols_if(t)                      In force at start of month t
l(0)                       pols_if_init                    In force at the valuation date
(none)                     pols_if_at(t, BEF_NB)           Carried in from month t - 1
(none)                     pols_if_at(t, BEF_DECR)         After new business: l(t)
(none)                     pols_if_at(t, BEF_MAT)          Before maturity: l(t)
(none)                     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
(none)                     pols_maturity(t)                Maturities: always zero
(premium income)           premiums(t)                     Premium income
(death claims)             claims_death(t)                 Death claims
(surrender outgo)          claims_lapse(t)                 Surrender payments
(claims)                   claims(t)                       Death and surrender claims
(withdrawal outgo)         withdrawals(t)                  Withdrawal payments
(maintenance)              expenses(t)                     Maintenance expenses
(percent of premium)       premium_taxes(t)                Premium tax / %-of-premium
NetCF(t)                   net_cf(t)                       Net liability cash flow
(none)                     check_av_roll_fwd_resid(t)      AV roll-forward residual
(none)                     check_margin_resid(t)           Margin identity residual
(none)                     result_pols()                   Counts and decrement rates
=========================  ==============================  ==========================

The table covers every symbol the notes define: the Model point attributes table, the
State variables table and the notation list, in that order, followed by the cash flow
rows; the cells running in force adds sit beside the symbols they open, key or count.
Three symbols have **no cells at all**, and are carried in the table as ``(not
modelled)`` so that the absence is recorded rather than silent: ``grace_flag(t)``, the
one of the notes' ten state variables with no counterpart here, because the grace
cascade is a diagnostic and no in-grace state is held (:func:`is_shortfall`);
``premium_mode``, because every premium in this model is monthly **[std]**; and
``earned_rate(t)``, the input the notes' optional NGE revision rule would need
(:func:`crediting_rate_ann`).

Eight names needed care.

The notes' ``risk_class`` is :func:`rate_class` here, and the model point table column
is ``rate_class`` too. The name is taken from ``Term_US_S``/``BasicTerm_S``, which
this library follows ahead of the notes wherever the two collide; ``rate_class`` also
avoids reading as Python's ``class``. The six classes themselves are the product
spec's, unchanged.

``l(t)`` in the notes is the in-force probability at the **start** of month ``t``, before
that month's decrements, with ``l(0) = 1``; ``pols_if(t)`` is the same quantity under
``BasicTerm_S``'s name, after the month's new business, so ``pols_if(t) = l(t)``. On a
point issued at ``t = 0``, ``pols_if(0)`` is the issued count, the notes' ``l(0)``, while
``pols_if_init()`` is 0, the count already in force at the valuation date; on a point in
force the two are one count. The notes' recursion ``l(t+1) = l(t)(1 - q_m(t))(1 - w_m(t))``
is the ``pols_if_at(t + 1, BEF_NB)`` step. Every BOM cash flow is weighted by
``pols_if(t)``, which is the notes' own ``l(t)`` weighting; take care not to read ``l(t)``
as an end-of-month count, which would weight every flow by the survivors of the month's
own decrements.

The notes write the monthly deduction as ``MD(t)`` and split it into a per-policy
charge, a per-unit charge, rider charges and the COI charge. ``CashValue_SE`` calls the
non-COI part of an account-value deduction ``maint_fee``; that name is kept here for
:func:`maint_fee_pp`, and :func:`mth_deduction_pp` is the notes' ``MD(t)`` in full.
:func:`expenses` is something different -- the insurer's own **[std]** maintenance
expense of $75 per policy per year, a cash flow, not a charge against the account
value. The two must not be confused: ``maint_fee`` is income, ``expenses`` is outgo.

The surrender-charge run-off ``SC(t) = max(0, (9.00 - (d(t) + 1)/12) x U)`` counts the
**current** month: one twelfth of a year's amortization is already earned in the issue
month, so the charge is $8.916667 per $1,000 in the issue month, not $9.00. The month
count in :func:`surr_charge_rate` is therefore ``duration_mth(t) + 1``, not
``duration_mth(t)``; using the completed months alone shifts the whole run-off by a
month.

``q_coi`` is quoted per $1,000 of net amount at risk **per month** and ``e_unit`` per
$1,000 of face per month, so both are divided by 1,000 -- or multiplied by
:func:`units` -- before they meet a currency amount. :func:`coi_rate` is therefore not
comparable with ``CashValue_SE.coi_rate``, which is a rate per unit of account value.

``surr_charge_pp(t)`` is the surrender charge *scheduled* at month ``t``;
``surr_charge(t)`` is the amount actually *collected* from lapsing policies, which is
capped by the account value because :func:`csv_pp` is floored at zero. In the first
policy years the schedule exceeds the account value and the two differ by a lot.

The notes' cash flow table lists "Withdrawal outgo" beside "Death claims" and
"Surrender outgo", but a partial withdrawal is a payment made on the **owner's
election**, not on a contingency, so it is not a claim here: it is :func:`withdrawals`,
its own cash flow line and its own ``result_cf()`` column, and no ``kind`` of
:func:`claim_pp` is a withdrawal. The consequence to hold on to is that
:func:`claims`, the total, is the death and surrender total *only*, so :func:`net_cf`
subtracts :func:`withdrawals` as a separate term. The per-policy amount
stays :func:`wd_pp`, which is the notes' ``W(t)``.

Finally, the notes write ``AV'(t)`` for one quantity and use it for two: the balance
the monthly deduction comes out of, and the balance the death benefit and the net
amount at risk are measured against. The two coincide until a policy in permanent
shortfall drives the account value negative -- which this model does not prevent,
because it does not terminate such a policy (:func:`is_shortfall`).
:func:`av_pp_at(t, BEF_FEE)<av_pp_at>` is the first and stays signed;
:func:`av_pp_db_basis` is the second and is floored at zero **[std]**, so an Option B
death benefit can never fall below the face amount.

.. rubric:: Codes

What :mod:`~.UL_US_S` spells as text, a timing or a kind, 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)``.

=============  =====  ===============================================================
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      :func:`av_pp_at`, :func:`av_at`: the account value carried in
BEF_WD         4      :func:`av_pp_at`, :func:`av_at`: after the net premium
BEF_FEE        5      :func:`av_pp_at`, :func:`av_at`: after the withdrawal and its fee
BEF_INV        6      :func:`av_pp_at`, :func:`av_at`: after the monthly deduction
EOM            7      :func:`av_at`: after the interest credit, 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
=============  =====  ===============================================================

The model has two families of timing, the count's and the account value's, 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 account value's in the
order of their instants within the month, ``EOM`` last. 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. A code a cell takes indexes that cell's cache, a C array
of eight codes a month for each of the five cells that take one, since every 2-D cache
of the model has one width (``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 ``omega_age`` among them, two of
the contract's bounds that the compiled model's caches are sized from (:func:`proj_len`).

.. rubric:: Reporting cells

:func:`model_point`, the label accessors :func:`sex`, :func:`rate_class`,
:func:`db_option`, :func:`qual_test`, :func:`premium_type` and :func:`surr_charge_id`,
the reports :func:`result_cf`, :func:`result_pols` and :func:`result_av`, and the checks
:func:`check_av_roll_fwd` and :func:`check_margin` are written for a reader and for the
comparison with :mod:`~.UL_US_S`, which has every one of them: a table row, text,
DataFrames and two verdicts. No other cell calls them: each reads the number ``Data``
decoded from the same column instead, the decodes' flags, the schedules 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 a column of numbers as
ints, and the compiled accessor returns the same. Every other cell returns a C ``bint``,
``long long`` or ``double``, and so do the two checks, which may stay Python but compile
to a ``bint``, their verdict, as their per-month residuals, ``*_resid``, compile to a
``double``.
"""

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`` reads it as ``UL_US_S`` reads it, ``int`` of the number, so a fractional age truncates toward zero. """ return int(data.age_at_entry()[idx]) # noqa: F821
[docs] def sex(): """The sex of the selected model point, M or F. A reporting cell (the Space docstring): ``Data`` joins the COI scale by it, through :func:`coi_schedule`, and no projection cell reads it here. """ return model_point()["sex"]
[docs] def rate_class(): """The underwriting class of the selected model point (one of six). A reporting cell (the Space docstring): ``Data`` joins the class factor and the COI scale by it, :func:`class_factor` and :func:`coi_schedule`, and no projection cell reads it here. """ return model_point()["rate_class"]
[docs] def sum_assured(): """The initial total face amount F of the selected model point, the face at issue. The face the surrender charge is quoted on, whatever later withdrawals cut it to [S3], and 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`. From ``Data.sum_assured``. """ return float(data.sum_assured()[idx]) # noqa: F821
[docs] def db_option(): """The death benefit option: ``"A"`` (level) or ``"B"`` (face plus account value). Option C (return of premium) is out of scope in the product spec. A reporting cell (the Space docstring): ``Data`` decodes the column into :func:`is_db_option_a` and :func:`is_db_option_b`, and no projection cell reads it here. """ return model_point()["db_option"]
[docs] def is_db_option_a(): """Whether the death benefit is Option A, the level face, from ``Data.is_db_option_a``. ``Data`` decodes the ``db_option`` column, 1 where it is ``"A"``, so that no monthly cell branches on text; :func:`db_pp` and :func:`face_reduction_pp` read this instead. """ 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. From ``Data.is_db_option_b``, 1 where ``db_option`` is ``"B"``, read by :func:`db_pp`, which raises on a point that is neither A nor B, as ``UL_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. CVAT is out of scope in the product spec, so :func:`corridor_factor` raises on anything else rather than silently applying GPT corridor factors. A reporting cell (the Space docstring): ``Data`` decodes the column into :func:`is_gpt`, and no projection cell reads it here. """ return model_point()["qual_test"]
[docs] def is_gpt(): """Whether the point elected the Guideline Premium Test, from ``Data.is_gpt``. 1 where ``qual_test`` is ``"GPT"``, read by :func:`corridor_factor`, which raises on any other test, as ``UL_US_S``'s does: CVAT is out of scope in the product spec. """ 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): ``Data`` decodes the column into :func:`is_level_premium`, :func:`is_single_premium` and :func:`is_target_premium`, and no projection cell reads it here. """ return model_point()["premium_type"]
[docs] def is_level_premium(): """Whether the premium pattern is LEVEL, from ``Data.is_level_premium``. One of the three decodes of the ``premium_type`` column that :func:`premium_pp` branches on, so that no monthly cell compares text; :func:`premium_pp` raises on a point that is none of the three, as ``UL_US_S``'s does. """ return bool(data.is_level_premium()[idx]) # noqa: F821
[docs] def is_single_premium(): """Whether the premium pattern is SINGLE, from ``Data.is_single_premium``. A decode of the ``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, from ``Data.is_target_premium``. A decode of the ``premium_type`` column, read by :func:`premium_pp`. """ return bool(data.is_target_premium()[idx]) # noqa: F821
[docs] def premium_pp_ann(): """The planned annual premium per policy; a billing target only [S3]. From ``Data.premium_pp_ann``. """ return float(data.premium_pp_ann()[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, ``Data.wd_pp``, a monthly amount, **0 in every shipped model point**: the notes give no withdrawal utilization pattern, so the behaviour is left to the data **[std]**. Read once a point here, so that :func:`wd_pp`, a monthly cell on the account value's chain, reads no table in its own formula. """ return float(data.wd_pp()[idx]) # noqa: F821
[docs] def load_prem_rate(): """The current premium load rate, 6% **[std]** (guaranteed maximum 9%) [S1]. The load is itself a non-guaranteed element in the source design, which is why it sits in the model point table rather than in a Reference. From ``Data.load_prem_rate``, which refuses a load outside 0 to 1. """ return float(data.load_prem_rate()[idx]) # noqa: F821
[docs] def av_pp_init(): """AV entering month 0: the account value per policy at the valuation date. The ``av_pp_init`` column, ``UL_US_S``'s own and the notes' ``av_initial``: the balance at the close of policy month ``duration_mth_init() - 1``, before any month-0 event, which is what ``UL_US_S`` carries into the month as ``av_pp_at(d, BEF_PREM)`` at ``d = duration_mth_init()``. It is the opening balance of the account value chain at :func:`t_entry`, ``av_pp_at(0, BEF_PREM)``. Zero for a point not yet in force, which is issued with no account value. ``Data`` refuses a negative one: an account value below zero is an artifact of the grace cascade the model does not implement, which no policy in force can hold. From ``Data.av_pp_init``. """ return float(data.av_pp_init()[idx]) # noqa: F821
[docs] def loan_bal_init(): """L entering month 0: the policy loan balance per policy at the valuation date. The ``loan_bal_init`` column, ``UL_US_S``'s own and the notes' ``loan_balance_initial``: the debt outstanding at the close of policy month ``duration_mth_init() - 1``, interest accrued to then included, before any month-0 event. It is the opening balance of :func:`loan_bal_pp_bom` at :func:`t_entry`, the loaned portion that month 0's interest credit, shortfall test and death claim read. Zero for a point not yet in force. From ``Data.loan_bal_init``. """ return float(data.loan_bal_init()[idx]) # noqa: F821
[docs] def sum_assured_init(): """F entering month 0: the total face amount in force at the valuation date. 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 ``UL_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 base, and ``Data`` refuses a value above it, since face increases are not modelled. Zero for a point not yet in force, which is issued at :func:`sum_assured`. ``UL_US_S`` opens its in-force point at the face at issue. From ``Data.sum_assured_init``. """ return float(data.sum_assured_init()[idx]) # noqa: F821
[docs] def wd_used_year_init(): """The free withdrawal allowance already used in the policy year under way, per policy. The ``wd_used_year_init`` column: the free part of every withdrawal taken since the anniversary on or before the valuation date, through policy month ``duration_mth_init() - 1``, which is what ``UL_US_S`` carries into the month as ``wd_used_year(d)``. :func:`wd_used_year` opens from it at :func:`t_entry`, so month 0's free amount is what is left of the year's 10%. The cell's name already says it restarts each policy year, so the column takes no ``_ytd``: on a point valued on an anniversary the year has just begun, the usage is 0, and ``Data`` refuses any other value there. Zero for a point not yet in force. ``UL_US_S`` opens its in-force point with the year's allowance unused. From ``Data.wd_used_year_init``. """ return float(data.wd_used_year_init()[idx]) # noqa: F821
[docs] def cum_prem_init(): """CumPrem entering month 0: premiums less withdrawals per policy before the valuation. 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 ``UL_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. ``ULSG_US_S`` gives the same column this name. From ``Data.cum_prem_init``. It may be negative. The notes' "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; ``Data`` holds the account value, the loan, the face and the usage to zero or more, and this to a number. Zero for a point not yet in force. ``UL_US_S`` opens its in-force point with none paid. """ return float(data.cum_prem_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. It is what ``UL_US_S`` carries into the month as ``is_mec(d - 1)``. :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. ``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. From ``Data.is_mec_init``, an int64 vector, so 1.0 reads as 1, and True. Zero for a point not yet in force. ``UL_US_S`` opens its in-force point with the latch off. """ return bool(data.is_mec_init()[idx]) # 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 account value, 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. From ``Data.policy_count``. """ 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. ``UL_US_S``'s cells 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``: 120 for point 3, ``UL_US_S``'s in-force cell, 126 for point 6, the same policy six months on, 0 for a policy issued at the valuation date, and -25 for point 9, to be issued 25 months after it, which ``Data`` admits up to ``future_horizon_mth`` months ahead. This is the notes' ``policy_month_offset``, an elapsed count, already 0-based, and ``UL_US_S``'s cells and column of the same name, which count from the first projected month; 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, from ``Data.duration_mth``. """ return int(data.duration_mth()[idx]) # noqa: F821
[docs] def has_surr_charge(): """Whether a surrender charge schedule applies to this model point. From ``Data.has_surr_charge``, 1 where the column reads True. """ 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, into :func:`surr_charge_rate_max` and :func:`surr_charge_runoff_years`, and no projection cell reads it here. A point without a charge is never refused for it, so it may be blank, read as NaN, or a number, as the column reads, and is returned as read. """ 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. The ``sc_per_1000_init`` column of this point's row of *surr_charge_table.csv*, $9.00 on the shipped ``UL9`` schedule; :func:`surr_charge_rate` amortizes it linearly from here. ``Data.surr_charge_rate_max`` joins it to the points by ``surr_charge_id``, once the table and the join are checked, so that no projection cell reads the table. :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 ``KeyError``, naming the point, where stage ``E``'s ``.loc`` raised it. """ rate = float(data.surr_charge_rate_max()[idx]) # noqa: F821 if not data.has_surr_charge_schedule()[idx]: # noqa: F821 raise KeyError(f"point_id {point_id()}: surr_charge_table.csv has no schedule " f"for its surr_charge_id") return rate
[docs] def surr_charge_runoff_years(): """The number of policy years over which the schedule's charge runs off. The ``runoff_years`` column of this point's row of *surr_charge_table.csv*, 9 on the shipped ``UL9`` schedule, read as a float: :func:`surr_charge_rate` amortizes :func:`surr_charge_rate_max` over it, and :func:`lapse_shock_year` is the year after it. Joined by ``Data.surr_charge_runoff_years`` as :func:`surr_charge_rate_max` is, which refuses on a point with a charge a run-off of 0, which ``surr_charge_rate`` would divide by, or one of ``2**53`` years or more in size, the bound every number read as an int is held to: the compiled ``int()`` in :func:`lapse_shock_year` converts it through a Python int to a C ``long long``, exact below ``2**63`` and raising ``OverflowError`` past it. Read by those two only where :func:`has_surr_charge` is true; on a point without a charge it reads the schedule where the table holds its id, as at stage ``E``, and raises ``KeyError``, naming the point, where it does not, as :func:`surr_charge_rate_max` does. """ years = float(data.surr_charge_runoff_years()[idx]) # noqa: F821 if not data.has_surr_charge_schedule()[idx]: # noqa: F821 raise KeyError(f"point_id {point_id()}: surr_charge_table.csv has no schedule " f"for its surr_charge_id") return years
[docs] def gsp(): """The guideline single premium (GPT compliance input) [S3], from ``Data.gsp``.""" return float(data.gsp()[idx]) # noqa: F821
[docs] def glp(): """The guideline level premium (GPT compliance input) [S3], from ``Data.glp``.""" return float(data.glp()[idx]) # noqa: F821
[docs] def seven_pay_prem(): """The 7-pay premium (IRC 7702A compliance input) [S3], from ``Data.seven_pay_prem``.""" return float(data.seven_pay_prem()[idx]) # noqa: F821
[docs] def duration_mth(t): """d(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 0 in the issue month, ``t = 0`` for a point issued at the valuation date, and negative before issue. This is the elapsed count in lifelib's sense (``CashValue_SE.duration_mth``) and the notes' month index; the surrender charge run-off counts the current month as well, ``duration_mth(t) + 1`` -- see :func:`surr_charge_rate`. """ 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, 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 from ``t``, and the key every policy-year table (*coi_rates.csv*, *lapse_table.csv*, *prem_persistency.csv*) is read 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)``. This is the notes' ``x + y - 1``. Age changes on the policy anniversary, not on the birthday, which is the ANB convention the whole model is built on **[std]**. Before issue it is below the issue age, where no table is read at it. """ return age_at_entry() + duration(t)
[docs] def omega_mth(): """The policy month at which the projection ends, the first at attained age 121. ``12 * (omega_age - age_at_entry() + 1)``: 1,032 at issue age 35. The mortality table ends at ``omega_age`` (120), where the annual rate is 1.0, so the last projected month, ``omega_mth() - 1``, is the last at attained age 120. It is ``UL_US_S``'s frame length, counted from issue on the policy clock; :func:`proj_len` counts from the valuation date instead. The contract has no maturity date [S2][S3], so the cell is named for ``omega_age``, the end of the table, and not for an event of 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`). """ return 12 * (omega_age - age_at_entry() + 1) # noqa: F821
[docs] def proj_len(): """The number of months from the valuation date to the end of the projection. ``omega_mth() - duration_mth_init()``: 1,032 for a policy issued at age 35 at the valuation date, 912 for point 3, in force 120 months, and 1,057 for point 9, 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 :func:`result_cf`, and ``proj_len() - 1`` is the last projected month, the last at attained age 120. The contract has no maturity date [S2][S3]; the projection is truncated by mortality, not by the policy. Three kinds of point have no frame the contract issues, and each raises here, naming the point, rather than projecting what the contract does not hold, in this order: * one issued above ``omega_age``, 120, which would never be in cover: ``UL_US_S`` projects it as months in which nothing happens. Checked first, so that a point to be issued there is refused whenever it is to be issued; * one at or past the end of the projection at the valuation date, which an in-force extract should not carry; * one issued below ``issue_age_min``, 18, the youngest issue age ``product-spec.md`` admits. ``UL_US_S`` projects any age its tables serve, but the compiled model's caches are sized from the contract (``spec_sec.py``), so a younger point, whose frame and policy years run longer, would read past them. A fractional issue age is read as ``UL_US_S`` reads it, truncated, so 17.5 is 17 and refused. """ if omega_mth() <= 0: raise ValueError( f"point_id {point_id()}: age_at_entry {age_at_entry()} is above omega_age, " f"{omega_age}: a policy issued there would never be in cover") # noqa: F821 n = omega_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 {omega_mth()}, " f"attained age {omega_age + 1}") # noqa: F821 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 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 loan, the face, the year's withdrawal usage, the cumulative premium and the MEC latch all open there, from the model point's opening state on a point in force and from the issue values on any other. No cell in cover reads a month before it. """ 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) < omega_mth()``, false before issue and from ``t = proj_len()`` on. Outside cover every count, charge, premium, withdrawal, decrement rate, decrement, claim and flow is zero and every flag false, no table is read at a policy year or an attained age the policy does not have, and nothing reads a month past ``proj_len()``; the clocks and the inputs read on the valuation clock keep their values, and the lapse shock's multiplier its 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) < omega_mth()
[docs] def crediting_rate_ann(t): """i_cr: the current declared annual effective credited rate, 4.00% **[std]**. A non-guaranteed element under ASOP 2 [R8]. The base deterministic run holds the snapshot scale level, as the notes prescribe. The notes' optional revision rule ``i_cr(t) = max(i_guar, earned_rate(t) - spread)`` needs an earned-rate input the notes do not supply and is not implemented. An economic input, so it is read on the **valuation** clock: ``t`` counts months from the valuation date, and a declared-rate scenario would be indexed by it, one path for every point of a block, however old the policy. The shipped rate is flat, so the clock shows in no number. """ return crediting_rate_curr # noqa: F821
[docs] def inv_return_mth(t): """i_m: the monthly credited rate, ``(1 + i_cr)^(1/12) - 1``. 0.0032737 at the **[std]** 4.00% current rate. The contract credits daily on a 365-day year [S3]; monthly compounding is the model's discretization **[std]** -- do not also compound daily. """ return (1 + crediting_rate_ann(t)) ** (1 / 12) - 1
[docs] def guar_rate_mth(): """i_gm: the monthly guaranteed rate, ``(1 + i_guar)^(1/12) - 1`` = 0.0016516.""" return (1 + guar_rate_ann) ** (1 / 12) - 1 # noqa: F821
[docs] def naar_factor(): """The specimen's NAAR factor, ``1 + i_gm`` = 1.0016516 **[std]** at 2% [S3]. The death benefit is discounted one month at the **guaranteed** rate, never the credited rate; the specimen prints 1.0024663 = 1.03^(1/12) at its own 3% guarantee [S3]. """ return 1 + guar_rate_mth()
[docs] def loan_rate_mth(): """The monthly charged loan rate, ``(1 + r_L)^(1/12) - 1`` at r_L = 2.75%. The contract accrues daily and capitalizes annually [S3]; monthly compounding is the model's discretization **[std]**. """ return (1 + loan_rate_ann) ** (1 / 12) - 1 # noqa: F821
[docs] def prem_persistency(t): """pp(y): the fraction of the planned premium actually paid in policy year y **[std]**. 100% in year 1, declining 2 percentage points a year to a 70% floor from year 16, read from *prem_persistency.csv* at the policy year of month t by :func:`prem_persistency_py`. The shape is informed qualitatively by the SOA/LIMRA UL study [R7]; the levels are a standardization. Zero outside cover, before the table is read: before issue the valuation clock reaches policy years 0 and below. """ return prem_persistency_py(policy_year(t)) if is_active(t) else 0.0
[docs] def prem_persistency_py(y): """pp(y) in policy year y, from *prem_persistency.csv*: the table's one reader. ``Data.prem_persistency_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.prem_persistency_last_year()`` gives, which it reads from the table's key column once it has checked the keys and the factors, before any factor is read. A year below 1, before the table's first row, where ``UL_US_S``'s ``.loc`` raised ``KeyError``, is refused, naming the point and the year, so that the padding is never read. Keyed by the contractual policy year, so the table is read once a policy year rather than once a month; :func:`prem_persistency` calls it inside cover only. """ last = data.prem_persistency_last_year() # noqa: F821 if y < 1: raise ValueError(f"point_id {point_id()}: prem_persistency.csv has no factor for " f"policy year {y}") return float(data.prem_persistency_array()[min(y, last)]) # noqa: F821
[docs] def premium_pp(t): """GP(t): the gross premium per policy received at BOM of month t. ``LEVEL`` Planned annual premium / 12, times :func:`prem_persistency`. ``SINGLE`` One premium in the issue month, capped at the guideline single premium. ``TARGET`` As ``LEVEL`` but capped so cumulative premium stays inside the GPT limit **[std]**; the cap looks at the cumulative premium *before* this month's, ``cum_prem_pp(t - 1)``, so there is no circularity. In the first month on the books, :func:`t_entry`, that is :func:`cum_prem_init`, the premiums paid before the valuation date, 0 at issue: a TARGET point in force near its limit collects only what the limit still has room for. Zero from attained age 121, when premiums are no longer accepted [S2][S3], and zero outside cover. The pattern is read through its decodes, :func:`is_single_premium`, :func:`is_level_premium` and :func:`is_target_premium`, not as text. """ 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 elif is_level_premium(): return premium_pp_ann() / 12 * prem_persistency(t) elif is_target_premium(): level = premium_pp_ann() / 12 * prem_persistency(t) paid = cum_prem_pp(t - 1) if t > t_entry() else cum_prem_init() return min(level, max(0.0, gpt_limit(t) - paid)) else: raise ValueError("invalid premium type")
[docs] def prem_to_av_pp(t): """NP(t): the net premium credited to the account value, ``GP(t) x (1 - pl)``.""" return premium_pp(t) * (1 - load_prem_rate())
[docs] def prem_to_av(t): """Net premium credited to account value, 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. Withdrawals are allowed from the first policy anniversary and stop at attained age 121 [S3]. The amount is the constant monthly figure :func:`wd_pp_mth`, the model point's ``wd_pp`` column, from the valuation date on, **0 in every shipped model point**: the notes give no withdrawal utilization pattern, so the mechanics are implemented and the behaviour is left to the data **[std]**. Zero outside cover, before either contractual test, so that nothing is withdrawn at ``t = proj_len()`` whatever ``omega_age`` and ``charges_cease_age`` are set to. """ if not is_active(t): return 0.0 if duration_mth(t) < 12 * wd_first_year: # noqa: F821 return 0.0 if age(t) >= charges_cease_age: # noqa: F821 return 0.0 return wd_pp_mth()
[docs] def wd_used_year(t): """The free-withdrawal allowance already consumed in the current policy year. The notes' ``wd_used_year`` state variable, "free-withdrawal usage in current policy year, updated on withdrawal": reset to zero on each policy anniversary and increased month by month by the free part of each withdrawal taken since, ``min(W(t-1), wd_free_pp(t-1))``. It is a value entering month t, before month t's own withdrawal. This is what makes the notes' allowance an **annual** one. Without it the 10% is granted afresh every month, and a policyholder withdrawing 10% of the account value every month takes twelve full annual allowances in a policy year and never triggers the Option A face reduction of :func:`face_reduction_pp`. In the first month on the books, :func:`t_entry`, it is :func:`wd_used_year_init`, the usage of the policy year under way at the valuation date. The anniversary reset comes first, so in an anniversary month, the issue month included, it is 0 whatever the model point says, and ``Data`` refuses a non-zero usage on a point valued on an anniversary. Zero outside cover. """ if not is_active(t) or duration_mth(t) % 12 == 0: return 0.0 if t == t_entry(): return wd_used_year_init() return wd_used_year(t - 1) + min(wd_pp(t - 1), wd_free_pp(t - 1))
[docs] def wd_free_pp(t): """The free partial withdrawal allowance still available in month t **[std]**. ``max(0, 10% of AV - wd_used_year(t))``: the allowance is 10% of the account value measured after the premium and before the withdrawal, less the part of it already taken earlier in the same policy year, and it resets on each policy anniversary -- the notes' "free-amount rule (10% of AV per policy year)" with its ``wd_used_year`` state (:func:`wd_used_year`). In the first withdrawal month of a policy year nothing is used yet and this is the full 10%. The specimen's carve-out is the lesser of $10,000 and 10% of net cash surrender value, on the first withdrawal of each of the first 15 policy years [S3]; the composite simplifies to 10% of the account value, with no dollar cap and no 15-year limit **[std]**. """ allowance = wd_free_rate * av_pp_at(t, BEF_WD) # noqa: F821 return max(0.0, allowance - wd_used_year(t))
[docs] def wd_fee_pp(t): """wf: the $25 withdrawal fee, charged only in a month with a withdrawal [S2][S3]. The fee is retained by the insurer, so it is account-value outgo but not a liability cash flow; it appears in :func:`margin_expense`, not in :func:`claims`. """ return wd_fee if wd_pp(t) > 0 else 0.0 # noqa: F821
[docs] def face_reduction_pp(t): """The total face reduction forced by a withdrawal under Option A [S3]. Under Option A a withdrawal beyond the free amount would otherwise increase the net amount at risk, so the face is cut by the excess. The free amount is whatever is left of the policy year's allowance (:func:`wd_free_pp`), not a fresh 10% each month. Under Option B the withdrawal reduces the account value only, and this is zero. The option is read through its decode, :func:`is_db_option_a`. """ if not is_db_option_a() or wd_pp(t) <= 0: return 0.0 return max(0.0, wd_pp(t) - wd_free_pp(t))
[docs] def sum_assured_at(t): """F(t): the total face amount in force in month t, after any reductions. The face entering the first month on the books, :func:`t_entry`, is 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 face in month ``t`` is the previous month's less the reduction forced by this month's withdrawal, so ``F(t)`` already reflects a reduction taken at BOM of month ``t``, the first month's included. Face increases, elective decreases and option changes are not modeled, so the only movement is the Option A withdrawal reduction. Zero outside cover. """ if not is_active(t): return 0.0 if t > t_entry(): prev = sum_assured_at(t - 1) elif duration_mth_init() > 0: prev = sum_assured_init() else: prev = sum_assured() return max(0.0, prev - face_reduction_pp(t))
[docs] def units(t): """U: the total 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 is multiplied by 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): """cf(a): the GPT corridor factor at the attained age of month t [S3][R2]. 250% to age 40, grading to 101% above age 93, read by :func:`corridor_factor_at`. Only the Guideline Premium Test is modeled; CVAT is out of scope in the product spec, 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`. 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): """cf 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, which above it is 101%: 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, which keeps the call one level shallower. 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 av_pp_db_basis(t): """AV'(t) floored at zero: the balance the death benefit is measured against. The notes' step 4 sets the Option B death benefit to ``F + AV'(t)`` and step 5 measures the net amount at risk against the same ``AV'(t)``, both on the premise that ``AV'`` is a real account balance. It stops being one as soon as a policy in permanent shortfall keeps being projected: the grace and lapse-for-insufficiency cascade is not implemented (see :func:`is_shortfall`), so nothing terminates such a policy and its account value runs deeply negative. Fed to ``F + AV'`` unfloored that gives an Option B death benefit **below the face amount**, and in the end a negative one -- a death claim paid *by* the beneficiary, which no universal life contract can produce. Flooring the balance at zero here is **[std]**, and is the same floor :func:`csv_pp` already carries for the same reason: a negative account balance is an artifact of the missing termination, not a contract state. It holds the Option B death benefit at or above the face amount, and it stops the net amount at risk from growing with the shortfall and charging COI on a fund that is not there. Wherever ``AV'(t) >= 0`` -- every month of model points 1 and 3, and the first 677 of point 2's 1,032 months -- this is exactly ``av_pp_at(t, BEF_FEE)`` and changes nothing, so the worked example is untouched. """ return max(0.0, av_pp_at(t, BEF_FEE))
[docs] def db_pp(t): """DB(t): the death benefit per policy after the corridor test [S1][S3]. ``max(option_db, cf(a) 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 and withdrawal and **before** the monthly deduction. Taking the account value at that point is what removes the circularity the notes warn about: under Option B the death benefit depends on the account value and the net amount at risk depends on the death benefit, but with this BOM ordering neither depends on the deduction. The ``AV'(t)`` used here is :func:`av_pp_db_basis`, floored at zero **[std]**, so the death benefit is never less than the face amount; see that cells for why the floor is needed at all. 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_db_basis(t) 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): ``DB(t) / (1 + i_gm) - AV'(t)``, floored at zero [S3]. Two conventions here are the specimen's, not conveniences: 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 rate in the discount, or the post-deduction account value, makes the COI charge implicit and requires iteration, and produces small systematic COI errors. The ``AV'(t)`` subtracted is :func:`av_pp_db_basis`, the same floored balance the death benefit is measured on, so the two sides of the subtraction stay consistent. """ return max(0.0, db_pp(t) / naar_factor() - av_pp_db_basis(t))
[docs] def coi_schedule(): """The number of this point's guaranteed COI scale, its row of ``Data.coi_rate_array``. ``Data.coi_schedule`` at this point: ``Data`` numbers each issue-age cell of *coi_rates.csv*, its ``sex``, ``rate_class`` and ``age_at_entry``, from 1 in the order of those keys, and gives each point the number of its own, or 0 where the table has no scale for it. ``UL_US_S`` slices the scale, a Series, by the same three keys in ``coi_rate_scale``, which this replaces, since no compiled cell returns a Series. A point without a scale is projected as ``UL_US_S`` projects it while no COI rate is read, and refused by :func:`coi_rate_last_year` once one is. """ return int(data.coi_schedule()[idx]) # noqa: F821
[docs] def coi_rate_guar(t): """q_coi_guar(s): the guaranteed maximum monthly COI rate per $1,000 NAAR [S3]. A 2001 CSO-era specimen table, log-linearly interpolated between the printed anchor years **[std]**; it grades to 1000/12 at attained ages 112-120 and to zero from attained age 121. Read at the policy year of month t by :func:`coi_rate_guar_py`; 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_rate_guar_py(y): """q_coi_guar in policy year y, from this point's scale: the scale's one reader. ``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 without a scale, before any rate is read. A year below 1, where ``UL_US_S``'s slice raised ``KeyError``, is refused, naming the point and the year, so that the padding is never read. 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, the last year of its scale, which ``Data`` reads from the table's key columns once it has checked the keys and the rates. 87 on the shipped anchor cell, whose scale runs to attained age 121. A point the table has no scale for, schedule 0, has a last year of 0, and is refused here, naming it, where ``UL_US_S``'s slice raised ``KeyError``: when its first COI rate is read, and not before, since a point valued, or issued, at or past ``charges_cease_age`` never reads one, and ``UL_US_S`` projects it. 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()[idx] < 1: # noqa: F821 raise ValueError(f"point_id {point_id()}: coi_rates.csv has no scale for the " f"point's sex, rate_class and age_at_entry") return int(data.coi_rate_last_years()[idx]) # noqa: F821
[docs] def coi_rate(t): """q_coi(s): the current monthly COI rate, ``coi_curr_factor`` x guaranteed **[std]**. 60% of the guaranteed maximum at every duration. Current COI scales are not published -- only guaranteed maxima appear in the specimen [S3] -- so this factor is a pure modeling assumption and one of the two assumptions to sensitivity-test first. Note the units: this is 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. """ return coi_curr_factor * coi_rate_guar(t) # noqa: F821
[docs] def coi_pp(t): """The cost of insurance charge per policy, ``q_coi(y) / 1000 x NAAR(t)`` [S3]. Zero from attained age 121, when monthly deductions cease [S2][S3], and zero outside cover. """ 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): """rc(t): rider charges, 0 in the base model **[std]**. The notes carry this term in the monthly deduction so that rider modules can be added without changing the recursion [S3]. """ return 0.0
[docs] def maint_fee_pp(t): """The non-COI part of the monthly deduction per policy [S3]. ``e_pol + e_unit(y) x U + rc(t)``: the $7.50 per-policy administrative charge, the per-unit coverage charge of $0.26 per $1,000 of face per month in policy years 1-10 and $0.156 thereafter, and rider charges. Zero from attained age 121, when charges cease [S2][S3], and zero outside cover. 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. """ if not is_active(t) or age(t) >= charges_cease_age: # noqa: F821 return 0.0 if policy_year(t) <= expense_unit_step_year: # noqa: F821 e_unit = expense_unit_mth_1 # noqa: F821 else: e_unit = expense_unit_mth_2 # noqa: F821 return expense_pol_mth + e_unit * units(t) + rider_charge_pp(t) # noqa: F821
[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): the monthly deduction per policy, taken at BOM [S3]. ``e_pol + e_unit(y) x U + rc(t) + q_coi(y) / 1000 x NAAR(t)``, i.e. :func:`maint_fee_pp` plus :func:`coi_pp`. The deduction at the start of month t pays for month t's coverage: the specimen says the deduction provides coverage for the following policy month, which with BOM indexing is the month it is taken in. """ 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 av_pp_at(t, timing): """Account value per policy at an intra-month point of month t. The BOM events change the balance in this order, and ``timing`` names the point just before each of them: ``BEF_PREM`` Before the premium: the closing balance of the previous month, ``AV(t-1)``, or the model point's opening balance :func:`av_pp_init` in the first month on the books, :func:`t_entry` -- the account value at the valuation date on a point in force, 0 at issue. This is where the opening state enters the recursion, as in ``CashValue_SE``; :func:`av_pp` itself has no base case. The previous month's close is formed here, from this timing's own value at ``t - 1`` and month ``t - 1``'s net premium, withdrawal, fee, deduction and interest, the same sum in the same order as ``av_pp(t - 1)``, rather than called for, so the chain of calls back to :func:`t_entry` is one cell a month, where ``UL_US_S``'s ran through five. 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 the roll-forward reads; zero before issue. ``BEF_WD`` After the net premium, before the withdrawal. ``BEF_FEE`` After the withdrawal and its fee, before the monthly deduction. This is the notes' ``AV'(t)``, and the balance the death benefit, corridor test and net amount at risk are all measured against. ``BEF_INV`` After the monthly deduction, before interest. Interest is credited on this post-deduction balance; reversing the two overstates the account value by about one month's interest on the deduction every month. The end-of-month balance ``AV(t)`` is :func:`av_pp`. The three timings after ``BEF_PREM`` are zero outside cover, ``t = proj_len()`` included. """ if timing == BEF_PREM: if not 0 <= duration_mth(t) <= omega_mth(): return 0.0 if t == t_entry(): return av_pp_init() av = (av_pp_at(t - 1, BEF_PREM) + prem_to_av_pp(t - 1) - wd_pp(t - 1) - wd_fee_pp(t - 1) - mth_deduction_pp(t - 1)) loaned = loan_bal_pp_bom(t - 1) return av + ((av - loaned) * inv_return_mth(t - 1) + loaned * guar_rate_mth()) elif timing == BEF_WD: if not is_active(t): return 0.0 return av_pp_at(t, BEF_PREM) + prem_to_av_pp(t) elif timing == BEF_FEE: return av_pp_at(t, BEF_WD) - wd_pp(t) - wd_fee_pp(t) elif timing == BEF_INV: return av_pp_at(t, BEF_FEE) - mth_deduction_pp(t) else: raise ValueError("invalid timing")
[docs] def inv_income_pp(t): """Interest credited to the account value per policy at EOM of month t. The unloaned part of the post-deduction balance earns the current monthly rate and the loaned part earns the guaranteed monthly rate [S2][S3]:: (AV'(t) - MD(t) - L(t-1)) x i_m + L(t-1) x i_gm which is the notes' step 8 rearranged. The loaned portion is taken as the opening loan balance :func:`loan_bal_pp_bom` exactly, as the notes write it, without capping it at the account value. """ loaned = loan_bal_pp_bom(t) unloaned = av_pp_at(t, BEF_INV) - loaned return unloaned * inv_return_mth(t) + loaned * guar_rate_mth()
[docs] def av_pp(t): """AV(t): the account value per policy at the end of month t. The post-deduction balance plus one month's interest, for every month of the frame including the first on the books: the opening balance ``av_pp_init()`` enters through ``av_pp_at(t, BEF_PREM)``, not through a base case here. With no loans and no withdrawals this collapses to the notes' core recursion ``AV(t) = [AV(t-1) + NP(t) - MD(t)] x (1 + i_m)``, which in the issue month of a point projected from issue reproduces the contractual policy-date rule that the account value equals the net premium less the first monthly deduction [S3]. Zero outside cover, through its timings. """ return av_pp_at(t, BEF_INV) + inv_income_pp(t)
[docs] def loan_bal_pp_bom(t): """L(t-1): the policy loan balance per policy at the beginning of month t. The previous month's closing balance, or the model point's opening balance :func:`loan_bal_init` in the first month on the books, :func:`t_entry` -- the debt at the valuation date on a point in force, 0 at issue. This is the loaned portion the interest credit, the shortfall test and the death claim all read; it plays for the loan the part ``av_pp_at(t, BEF_PREM)`` plays for the account value, and like it forms the previous month's close itself, its own value at ``t - 1`` times ``(1 + r_L)^(1/12)``, the product :func:`loan_bal_pp` takes, rather than calling for it. So the chain back to :func:`t_entry` is one cell a month, where ``UL_US_S``'s ran through two. Zero outside cover: nothing reads the loan at ``t = proj_len()``, where it would turn the death claim on a death benefit of 0 negative. """ if not is_active(t): return 0.0 if t == t_entry(): return loan_bal_init() return loan_bal_pp_bom(t - 1) * (1 + loan_rate_mth())
[docs] def loan_bal_pp(t): """L(t): the policy loan balance per policy at the end of month t. ``L(t-1) x (1 + r_L)^(1/12)`` on the opening balance :func:`loan_bal_pp_bom`, for every month on the books, the first included. Interest accrues daily and is capitalized annually under the contract [S3]; monthly compounding is the model's discretization **[std]**. New loans and repayments are not modeled -- the notes give no utilization pattern -- so this only rolls the model point's opening balance forward. Zero outside cover. """ return loan_bal_pp_bom(t) * (1 + loan_rate_mth())
[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: return av_pp(t) * pols_if(t) return av_pp_at(t, timing) * pols_if(t)
[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_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)
[docs] def surr_charge_rate(t): """SC per $1,000 of initial face in month t **[std amount; mechanics [S3]]**. ``max(0, sc_init - (sc_init / runoff_years) x m / 12)`` where ``m`` is the number of months amortized **including the current one**, ``duration_mth(t) + 1``, and ``sc_init`` and ``runoff_years`` are the schedule's, :func:`surr_charge_rate_max` and :func:`surr_charge_runoff_years`. With the shipped schedule of $9.00 per $1,000 running off over 9 years this is the notes' ``max(0, 9.00 - (d(t) + 1)/12)``: $8.916667 in the issue month, $8.00 in the last month of policy year 1, and zero from policy month 107, the last month of policy year 9, onward. Using ``duration_mth(t)`` alone would shift the entire run-off by a month. Zero outside cover. """ 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): """CSV(t): the cash surrender value per policy, ``AV(t) - SC(t)``, floored at zero. The floor is **[std]**: the notes write ``CSV = AV - SC`` without one, but a negative cash surrender 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. """ return max(0.0, av_pp(t) - surr_charge_pp(t))
[docs] def ncsv_pp(t): """NCSV(t): the net cash surrender value, ``CSV(t) - L(t)``, floored at zero. This is what a surrendering policyholder is paid, and the notes' surrender outgo. """ 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(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 is_shortfall(t): """The grace trigger: ``AV'(t) - L(t-1) < MD(t)`` on a monthiversary [S2][S3]. A diagnostic. The full grace and lapse-for-insufficiency cascade is **not implemented**: the notes leave the in-grace account value treatment (deductions accrue as due and unpaid) and the cash flow of a cure payment undetermined, so no policy is terminated for insufficiency here. It is not inert. Of the three model points that are ``UL_US_S``'s own, its twins: * point 1, the worked-example anchor, is never in shortfall in any of its 1,032 months -- ``$150`` a month comfortably covers the ``$39.54`` issue-month deduction, and the account value grows from there; * point 3, the in-force cell, is never in shortfall in any of its 912 months; * point 2, the Option B cell, **is** in shortfall from ``t = 676`` (policy year 57, attained age 91) to the end of the projection, 356 months. Level $150 premiums stop covering a COI charge on a ~$100,000 net amount at risk at those ages. Point 7 is point 2 restated in force at that month, so it is in shortfall from ``t = 0`` for the whole of its frame. Because nothing terminates either, their deductions keep coming out of an account value that is already empty, and point 2 ends the projection about $1.84m overdrawn. That is an artifact of the missing cascade, and it is why the death benefit is measured on the floored :func:`av_pp_db_basis` rather than on a signed ``AV'``. Treat cash flows for a model point in shortfall as **not meaningful** past the trigger month; the README says so too. False outside cover, where every term is zero. """ return av_pp_at(t, BEF_FEE) - loan_bal_pp_bom(t) < mth_deduction_pp(t)
[docs] def cure_premium_pp(t): """The payment required to cure a grace: ``3 x MD(t)`` grossed up for the load [S3]. The specimen requires at least three times the monthly deduction due plus the premium load, so the gross payment is ``3 x MD / (1 - pl)``. A diagnostic; see :func:`is_shortfall`. ``Data`` admits a load of 1, which ``UL_US_S`` projects in full, since no report reads this cell, and at which this one divides by zero. ``UL_US_S`` raises Python's ``ZeroDivisionError: float division by zero`` there, and the compiled division's check would raise the same error with another message, so the divisor is checked first and ``UL_US_S``'s own error raised, the same in both engines. """ if 1 - load_prem_rate() == 0: raise ZeroDivisionError("float division by zero") return 3 * mth_deduction_pp(t) / (1 - load_prem_rate())
[docs] def cum_prem_pp(t): """CumPrem(t): cumulative premiums less withdrawals through month t. The running total for the GPT and 7-pay tests, 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. ``UL_US_S`` restarts it at 0 on its in-force point, the notes giving no opening cumulative-premium attribute **[std]**. The notes' "less a portion of withdrawals" is taken as the whole withdrawal **[std]**. Zero outside cover. """ if not is_active(t): return 0.0 prev = cum_prem_pp(t - 1) if t > t_entry() else cum_prem_init() return prev + premium_pp(t) - wd_pp(t)
[docs] def gpt_limit(t): """The guideline premium limit, ``max(GSP, GLP x policy years elapsed)`` [S3][R2]. 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 [S3][R2][R3]. 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)`` [R3][REG-R14]. 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. ``CumPrem(t) > 7-pay limit`` in any of the first seven policy years, **latched**: the flag stays set for the rest of the projection. The latch is not decoration. Under IRC 7702A the contract *is* a modified endowment contract once the 7-pay test fails, permanently and for every later year [R3][REG-R14]; and the in-year test itself stops applying in policy year 8, so an unlatched flag would quietly switch itself off exactly when the failure becomes permanent. The notes ask the base model to "flag (does not project) 7-pay failures", which a flag that turns itself off does not do. 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, and modeling it as a charge or refund would distort premium income [S3][R2][R3]. """ 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]**. The ``factor`` of this point's ``rate_class`` in *class_factor_table.csv*, joined to the points by ``Data.class_factor`` once ``data.class_count()`` has checked the table's classes and factors: a blank factor would otherwise reach :func:`mort_rate` as a missing value. A point whose class the table lacks, which ``UL_US_S`` fails on in every projection, is refused by ``Data`` at the join's first read, naming every such point. """ return float(data.class_factor()[idx]) # noqa: F821
[docs] def mort_rate(t): """The annual best-estimate mortality rate in month t, capped at 1. Base table times :func:`class_factor` times the A/E factor, which is 100% in the base run **[std]** with no mortality improvement. The shipped table is a small illustrative one **[std]**, *not* the 2015 VBT the notes recommend -- that family is licensed and may not be reproduced here. 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.0, as ``UL_US_S``'s and ``ULSG_US_S``'s are. A class factor above 1 -- 1.50 and 1.75 for the two tobacco classes -- carries the oldest ages' rates past 1, where the monthly rate ``1 - (1 - q)^(1/12)`` has no real value; at the shipped A/E a StdTob point's product first passes 1 at attained age 113. Where the product is at most 1, which is every rate ``UL_US_S``'s own points reach, the cap changes nothing. It is written ``min(q, 1.0)``, as ``UL_US_S`` writes it, the same float as ``min(1.0, q)`` wherever ``q`` is a number: Python's ``min``, and the compiled cell, keep their first argument unless a later one is smaller, so ``min(1.0, q)`` would turn a blank base rate or class factor, which ``UL_US_S`` reads as a missing value, into 1.0, certain death with every flow finite, where ``min(q, 1.0)`` keeps it missing. ``Data`` refuses both as it reads the tables (``data.mort_age_last()``, ``data.class_count()``), before any rate is read. Zero outside cover. """ 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_m(t): the monthly mortality rate, ``1 - (1 - q)^(1/12)``.""" return 1 - (1 - mort_rate(t)) ** (1 / 12)
[docs] def lapse_rate_base(t): """w_base(y): the base annual lapse rate by policy year **[std]**. 6% in year 1, 5% in year 2, 4% in years 3-10, 3% thereafter, read from *lapse_table.csv* at the policy year of month t by :func:`lapse_rate_base_py`. The shape is informed qualitatively by the SOA/LIMRA UL persistency studies [R7][REG-R20], whose detailed tables are behind a paid package, so the levels are a standardization. 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): """w_base in policy year y, from *lapse_table.csv*: the table's one reader. ``Data.lapse_rate_array()`` at the year, read as :func:`prem_persistency_py` reads its own table: policy years beyond the table take its last row, the last year ``data.lapse_last_year()`` gives once it has checked the keys and the rates, and a year below 1 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 shock. The first policy year with no surrender charge in any month, i.e. the run-off length plus one; because the run-off counts the current month the charge already reaches zero in policy month 107, the last month of policy year 9. Derived from the schedule's :func:`surr_charge_runoff_years` rather than hard-coded, so a different schedule moves the shock 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): """M_sc: the surrender-charge-expiry lapse shock multiplier, 2.0 **[std]**. Applied in the policy year :func:`lapse_shock_year` gives, and only there. The surrender charge suppresses surrender while it is positive and its expiry is a known industry shock point; product-specific studies are proprietary, so the size is a shape assumption. 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 comp_rate_ann(t): """r_comp(t): the competitor / market new-money rate driving dynamic lapse **[std]**. The base deterministic run sets it equal to the current credited rate, exactly as the notes prescribe, so :func:`lapse_rate_dyn_mult` is 1. An economic input, read on the **valuation** clock, as :func:`crediting_rate_ann` is. To switch interest-sensitive lapse on, override this cell's formula before the model computes anything; that is a formula override, which only modelx can make. """ return crediting_rate_ann(t)
[docs] def lapse_rate_dyn_mult(t): """M_rate(t): the interest-sensitive lapse multiplier **[std]**. ``min(3.0, 1 + 5 x max(0, r_comp(t) - i_cr(t) - 0.01))``: no effect until the competitor rate exceeds the credited rate by more than 100 basis points. Equal to 1 throughout the base run. """ excess = max(0.0, comp_rate_ann(t) - crediting_rate_ann(t) - lapse_dyn_threshold) # noqa: F821 return min(lapse_dyn_cap, 1 + lapse_dyn_slope * excess) # noqa: F821
[docs] def lapse_rate(t): """w_annual(y, t): the total annual lapse rate **[std]**. ``min(0.35, w_base(y) x M_sc(y) x M_rate(t))`` -- the base rate, the surrender-charge-expiry shock and the dynamic multiplier, capped **[std]**. """ 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): """w_m(t): the monthly lapse rate, ``1 - (1 - w_annual)^(1/12)``.""" return 1 - (1 - lapse_rate(t)) ** (1 / 12)
[docs] def pols_if(t): """Number of policies in force at the beginning of month t, the weight of row t. ``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 ``UL_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)
[docs] def pols_if_at(t, timing): """Number of policies in force at a point of month t, by ``timing``. The three timings ``UL_US_S``'s cell names: ``BEF_NB`` The count carried in from month t - 1, before month t's new business: the survivors of month t - 1's deaths and lapses, out of month t - 1's ``BEF_DECR`` count. 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 where the mortality table ends, not where the contract does, 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: ``UL_US_S``'s meaning, the ``BEF_DECR`` count, which its cell gives for this timing. The contract has no maturity date, 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, as it is not in ``Term_US_SEC`` and ``WholeLife_US_SEC``: the name keeps its S model's meaning. ``BEF_NB`` forms the count left at the end of month t - 1 itself -- month t - 1's ``BEF_NB`` count plus its :func:`pols_new_biz`, less its deaths and lapses, the products :func:`pols_death` and :func:`pols_lapse` take, in the order they take them -- rather than calling for it. So the chain of calls back to :func:`t_entry` is one cell a month, as ``UL_US_S``'s :func:`pols_if` chain was: a compiled model runs that chain on the C stack. ``UL_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: if not 0 <= duration_mth(t) <= omega_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) q = mort_rate_mth(t - 1) return prev - prev * q - prev * (1 - q) * lapse_rate_mth(t - 1) elif timing == BEF_DECR: return pols_if_at(t, BEF_NB) + pols_new_biz(t) elif timing == BEF_MAT: return pols_if_at(t, BEF_DECR) 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_m(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_m(t)) x w_m(t)``: death is applied before lapse **[std order]**, matching the notes' ``l(t+1) = l(t)(1 - q_m(t))(1 - w_m(t))``. 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. Universal life has no maturity date -- at attained age 121 charges cease, premiums stop and coverage continues for life [S2][S3]. The cells 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 last projected month do not mature either: the projection stops there because the mortality table does, and 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-1)``: the death benefit less the policy debt at the start of the month, :func:`loan_bal_pp_bom` [S3]. Due and unpaid deductions during grace would also be subtracted, but the grace cascade is not implemented. ``LAPSE`` ``NCSV(t)``, the net cash surrender value. A partial withdrawal is **not** a claim -- it is a payment on the owner's election rather than on a contingency -- so no ``kind`` here is a withdrawal. Its per-policy amount is :func:`wd_pp` and its cash flow is :func:`withdrawals`; the $25 fee is retained by the insurer and is not part of the payment. """ if kind == DEATH: return db_pp(t) - loan_bal_pp_bom(t) elif kind == LAPSE: return ncsv_pp(t) else: raise ValueError("invalid kind")
[docs] def claims_from_av(t, kind): """The part of a claim paid 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 has no maturity date. """ if kind == DEATH: return av_pp(t) * pols_death(t) elif kind == LAPSE: return av_pp(t) * pols_lapse(t) elif kind == MATURITY: 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)
[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 :func:`net_cf` subtracts. ``UL_US_S``'s ``claims(t, kind=None)`` is both the kinds and their total, a generator summed by Python's ``sum``, which compiles to neither a C parameter nor a C loop; here the kinds are two cells, the ``result_cf`` columns, and this is their total. Python's ``sum`` of floats is compensated, but of two it is their sum, rounded once, which is what this computes, and its ``0.0`` start keeps ``sum``'s, which turns two negative zeros to ``0.0``. So the total is ``UL_US_S``'s float in every month. Partial withdrawals are **not** here, neither as a kind nor in the total: a withdrawal is a payment on the owner's election rather than a claim, and is :func:`withdrawals`. So ``claims(t)`` is the death and surrender total only, and :func:`net_cf` subtracts the withdrawal row separately. """ return 0.0 + claims_death(t) + claims_lapse(t)
[docs] def claims_death(t): """Death claims in month t: :func:`pols_death` at the death benefit per policy, ``claim_pp(t, DEATH)``, an end-of-month event. The ``claims_death`` column of :func:`result_cf`.""" return claim_pp(t, DEATH) * pols_death(t) # noqa: F821
[docs] def claims_lapse(t): """Surrender claims at the end of month t: :func:`pols_lapse` at the net cash surrender value per policy, ``claim_pp(t, LAPSE)``. 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 at BOM of month t. ``W(t) x pols_if(t)``: a withdrawal is taken at the beginning of the month by the policies still in force, so it is weighted by :func:`pols_if` and not by a decrement. It is a cash flow line of its own -- the ``withdrawals`` column of :func:`result_cf` -- and not a ``kind`` of :func:`claim_pp`, because a withdrawal is a payment the owner elects rather than a claim on a contingency. The $25 withdrawal fee is retained by the insurer and is not part of the payment; see :func:`wd_fees`. Zero in every shipped model point: the mechanics are implemented and the utilization is left to the data **[std]**, as :func:`wd_pp` explains. """ return wd_pp(t) * pols_if(t)
[docs] def wd_fees(t): """Withdrawal fees retained by the insurer, for the policies in force. Account-value outgo but not a liability cash flow, so this appears in :func:`margin_expense` and not in :func:`claims`. """ return wd_fee_pp(t) * pols_if(t)
[docs] def inflation_factor(t): """The expense inflation factor, ``(1 + inflation_rate)^(t // 12)`` **[std]**. Expenses inflate by year, not by month, which is how the notes write the $75 per policy per year maintenance expense, and 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 anniversaries. ``UL_US_S`` steps on the policy year, ``(1 + inflation_rate)^(y - 1)``; on a point issued at ``t = 0`` the two are the same, and on point 3, in force 120 months, this model's expense is ``UL_US_S``'s divided by ``1.025^10``. Acquisition is not inflated (see :func:`expenses`). """ return (1 + inflation_rate) ** (t // 12) # noqa: F821
[docs] def expenses(t): """The insurer's own expenses in month t **[std]**. ``(acq + expense_maint / 12 x inflation) x pols_if(t)``, ``UL_US_S``'s formula in its order: the maintenance expense inflating at 2.5% a year, on the valuation clock, and ``expense_acq`` in the issue month, ``duration_mth(t) == 0``, not inflated, both 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 at the valuation date never bears it, because it was issued before. On a point issued at ``t = 0`` this is ``UL_US_S``'s charge bit for bit. The notes specify no acquisition expense for this product -- the higher per-unit charge in policy years 1-10 is the contractual acquisition-cost recovery, which is income, not outgo -- so ``expense_acq`` is zero and the term is carried only so products built on this chassis can switch it on. Zero outside cover, where the count carried into ``t = proj_len()`` would otherwise bear a maintenance expense. Not to be confused with :func:`maint_fee`, which is the charge *against the account value*. """ 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 and other percent-of-premium expense, 2.5% of premium **[std]**.""" 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 GP + 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): """Net liability cash flow in month t, **undiscounted**. ``premiums - death claims - surrender payments - withdrawals - expenses - premium taxes``, **income-positive** as in every model of this library. :func:`claims` carries the death and surrender rows only, so the withdrawal row is subtracted as its own term. Like the rest of this library the model projects *gross liability cash flows*: there is no discounting and no change in account value in this figure, because reserves are a separate layer that consumes these flows. Investment income on the account value is a credit to the policyholder, not an insurer cash flow, so it does not appear either -- see :func:`check_margin` for how it reconciles. """ return (premiums(t) - claims(t) - withdrawals(t) - expenses(t) - premium_taxes(t))
[docs] def check_av_roll_fwd(): """Check the account value roll-forward. Returns ``True`` when, for every projected month, the opening account value in force of month ``t + 1`` equals:: av_at(t, BEF_PREM) + prem_to_av(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 1, which is what ``math.isclose`` tests with both its tolerances at ``1e-9``. This pins the notes' processing order, in particular that interest is credited on the *post-deduction* balance and that decrements come after the credit. Each month's residual is :func:`check_av_roll_fwd_resid`, so a failure can be found by month, and a residual that is not a number fails. 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 1: one number a month, whose magnitude is within ``1e-9`` exactly where ``math.isclose`` with both tolerances at ``1e-9`` holds. Zero outside cover, before ``t + 1`` is read, so that nothing reads a month past ``t = proj_len()``. Returned as ``float(...)`` of the ratio, as the life chassis returns every residual: a real ratio is its own float, and one that is not real, as a decrement rate past 1 would make it in modelx, raises here rather than pass the check on its magnitude. """ if not is_active(t): return 0.0 av = (av_at(t, BEF_PREM) + prem_to_av(t) - withdrawals(t) - wd_fees(t) - mth_deduction(t) + inv_income(t) - claims_from_av(t, DEATH) - claims_from_av(t, LAPSE)) nxt = av_at(t + 1, BEF_PREM) return float((nxt - av) / max(abs(nxt), abs(av), 1.0))
[docs] def check_margin(): """Check the net cash flow against the expense and mortality margins. Returns ``True`` when, for every projected month:: net_cf(t) == margin_expense(t) + margin_mortality(t) + av_change(t) - inv_income(t) + min(loan_bal_pp(t), csv_pp(t)) * pols_lapse(t) to within ``1e-9``, relative to the larger side and 1, as for :func:`check_av_roll_fwd`; each month's residual is :func:`check_margin_resid`, and a residual that is not a number fails. The last three terms 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; the loan term is 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. ``UL_US_S``'s identity takes the whole loan in every month, so it is off by ``(CSV(t) - L(t)) x pols_lapse(t)`` once the loan exceeds the cash value, and its check fails on a projection that is right; on every shipped model point the cash value covers the loan, and the two checks 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 margins, the change in account value, the investment income and the loan a surrender recovers, that :func:`check_margin` sets out, over the larger of the two sides in magnitude and 1, as :func:`check_av_roll_fwd_resid` measures its own. Zero outside cover, before :func:`av_change` would read ``t + 1``. Returned as ``float(...)`` of the ratio, as :func:`check_av_roll_fwd_resid` is. """ if not is_active(t): return 0.0 rhs = (margin_expense(t) + margin_mortality(t) + av_change(t) - inv_income(t) + min(loan_bal_pp(t), csv_pp(t)) * pols_lapse(t)) lhs = net_cf(t) return float((lhs - rhs) / max(abs(lhs), abs(rhs), 1.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. The columns are ``UL_US_S``'s. The two claim columns are the cells of their names, :func:`claims_death` and :func:`claims_lapse`, each the claim of the ``kind`` it is named for, and partial withdrawals sit in their own ``withdrawals`` column rather than among the claims. The cash flow columns sum to ``net_cf`` under the income-positive sign convention: ``premiums`` less every other flow. """ 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_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, death first, and its maturities, which are always zero. Row by row, ``pols_if`` at ``t + 1`` is ``pols_if`` less the three outflows of month t, plus the new business of month ``t + 1``. Then ``UL_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 are the columns of the worked example in the technical notes, in the notes' own order: ``AV(t-1)``, ``NP``, ``AV'``, ``DB``, ``NAAR``, ``COI``, ``MD``, ``AV' - MD``, interest, ``AV(t)``, followed by the surrender and loan values. The index runs ``t = 0 .. proj_len() - 1``, as in :func:`result_cf`; on a point issued at the valuation date row ``t = 0`` is the notes' issue-month row, and on a point issued later the rows before issue are zeros. The ``loan_bal_pp`` column is the end-of-month balance ``L(t)``. """ ts = list(range(proj_len())) return pd.DataFrame( # noqa: F821 { "av_pp_bef_prem": [av_pp_at(t, BEF_PREM) for t in ts], "prem_to_av_pp": [prem_to_av_pp(t) for t in ts], "av_pp_bef_fee": [av_pp_at(t, BEF_FEE) for t in ts], "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], "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 )
# --------------------------------------------------------------------------- # References data = ("Interface", ("..", "Data"), "auto") idx = 0 BEF_NB = 0 BEF_DECR = 1 BEF_MAT = 2 BEF_PREM = 3 BEF_WD = 4 BEF_FEE = 5 BEF_INV = 6 EOM = 7 DEATH = 0 LAPSE = 1 MATURITY = 2 issue_age_min = 18 omega_age = 120 charges_cease_age = 121 guar_rate_ann = 0.02 crediting_rate_curr = 0.04 coi_curr_factor = 0.6 expense_pol_mth = 7.5 expense_unit_mth_1 = 0.26 expense_unit_mth_2 = 0.156 expense_unit_step_year = 10 loan_rate_ann = 0.0275 wd_fee = 25.0 wd_free_rate = 0.1 wd_first_year = 1 mort_ae_factor = 1.0 lapse_shock_mult = 2.0 lapse_dyn_slope = 5.0 lapse_dyn_threshold = 0.01 lapse_dyn_cap = 3.0 lapse_rate_cap = 0.35 expense_acq = 0.0 expense_maint = 75.0 inflation_rate = 0.025 premium_tax_rate = 0.025 pd = ("Module", "pandas")