The Projection Space#
The by-contract projection of the MYGA_US_SEC model.
The Space is parameterized by idx, the position of a model point in the table and in
every Data vector, as basiclife.BasicTerm_SC is:
Projection[7] is an ItemSpace projecting the table’s eighth row, model point 8, the
anchor cell in force 12 months at the valuation date, on its first contract
anniversary, and point_id() is its label:
>>> Projection[7].result_cf() # one row per month from the valuation date
>>> Projection[7].result_av() # its account value and Model #805 floor
>>> Projection[7].point_id() # 8, 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/fixed_deferred_annuity/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 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 MYGA_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
MYGA_US_S is rewritten where it depends on where the projection starts, where it
must answer for a month outside cover, where it passed a policy month as t, or where
it reads a table or text the compiled model holds as numbers; every other is
MYGA_US_S’s own. products/fixed_deferred_annuity/model-sec.md lists the
rewritten cells with the reason for each.
Input data
Inputs are external files: plain CSVs living in the model folder’s parent directory,
products/fixed_deferred_annuity/, 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
MYGA_US_SEC folder without its parent’s CSVs produces a model that reads and then
fails on first evaluation.
The readers and the filename References live on the sibling Data
Space, reached here through the data Reference, so each file is read once per model
rather than once per model point. The six assumption tables are the files
MYGA_US_S reads, read in place; the model point table is this model’s own. The
projection reads each table as Data holds it in arrays, built from the table checked,
its keys read by value, and through one cell of its own:
Reference (on Data) |
Arrays the projection reads |
File |
|---|---|---|
model_point_file |
data.premium() and the vectors |
model_point_table_sec.csv |
mort_table_file |
data.mort_table_array() |
mort_table.csv |
surr_charge_file |
data.surr_charge_array() |
surr_charge_table.csv |
surr_charge_age_cap_file |
data.surr_charge_age_cap_array() |
surr_charge_age_cap.csv |
rate_scenario_file |
data.market_rate_array(), data.mva_ref_yield_array() |
rate_scenario.csv |
withdrawal_file |
data.wd_amount_array() |
withdrawal_table.csv |
mva_factor_file |
data.mva_factor_array() |
mva_factor_table.csv |
The model point’s attributes are each one element of a Data vector, read by an
accessor of the column’s name, premium_pp reading data.premium()[idx];
model_point(), the whole row, is for a reader. mort_rate_at(),
surr_charge_rate(), surr_charge_age_cap_at(), scenario_rate(),
wd_scheduled_pp() and mva_duration_factor() are the tables’ readers, in that
order. The age cap and the mortality are read through cells keyed by the attained age,
the duration factors at the whole years of the MVA term, and the surrender charge, the
scenario and the withdrawals at the month; the mortality, the scenario and the
withdrawals at the row Data numbers the point’s sex, scenario_id or
wd_schedule_id by, and the surrender charge at the schedule code
surr_charge_id() returns (Data’s docstring, The vectors).
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 contract, month t runs from time t to time t + 1, and
the frame is t = 0 .. proj_len() - 1, where proj_len() counts the months from
the valuation date to the deemed maturity at attained age 100. 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 contract has been in force
at time t: duration_mth(t) = duration_mth_init() + t, where
duration_mth_init() is read from the model point — positive for a contract in
force at the valuation date, in any month of its contract year, 0 for one issued at it,
-k for one issued k months later, at most ten years later. It is the technical
notes’ month index, and everything contractual reads it. The contract year is
policy_year(t) = duration(t) + 1 with duration(t) = duration_mth(t) // 12, so the
anniversaries fall at the start of the months whose duration_mth(t) is a
multiple of 12, and the attained age is age(t) = age_at_entry() + duration(t). On
that clock run the guarantee periods, the initial term and each renewal of n years;
the 30-day window in the first month of each renewal period; the redeclaration months;
the surrender charge schedules, their clock and the attained-age cap; the MVA term; the
base lapse years and the dynamic-lapse exponent; the free-withdrawal year and its reset;
and the scheduled withdrawals, whose t in withdrawal_table.csv is a policy month.
Every renewal period is n years, as the product has it, so the position in the
guarantee period, the surrender-charge clock and the window are derived from
duration_mth(t) alone. The anchor cell in force 12 months is in contract year 2 at
attained age 61 at t = 0, where its $4,000 withdrawal of policy month 12 falls.
Two inputs read the valuation clock instead. The rate scenario — the market
competitor rate market_rate(t) and the MVA reference yield mva_ref_yield(t) — is
a path in calendar time, shared by every point of a block, so its t in
rate_scenario.csv is a valuation month. A rate fixed in the past, the declared rate of
a renewal period or the i0 locked at its start, is read from the scenario at the
valuation month it was fixed in, or from the opening state where that month is before
t_entry(). Each shipped scenario is one flat row, so no shipped number depends on
the clock it is read on. And expense inflation, inflation_factor(t) = (1 +
inflation_rate) ** (t // 12), keeps MYGA_US_S’s annual step but takes it every
twelve months from the valuation date, so the maintenance charge is in valuation-date
dollars for every point alike. Acquisition is charged per contract issued, in the issue
month, and is not inflated, as in basiclife.BasicTerm_SE.
Within a month: the free-withdrawal counters roll, the guarantee-period boundary is
applied, the elective withdrawal is taken, the annuitization elections are taken on the
account value after it, before crediting (annuitization_pp()), and the tax basis
is updated — all at the beginning of the month (BOM) — then interest is credited, the
Model #805 floor rolls forward and decrements are applied in the order annuitization,
mortality, surrender at the end of the month (EOM) [std], with the death and
surrender benefits valued on the post-crediting account value. A contract’s single
premium, its acquisition commission and its premium tax are beginning-of-month flows of
its issue month, the month with duration_mth(t) = 0.
Twelve monthly factors (1 + i_cr)^(1/12) reproduce the declared effective annual
rate exactly, so av_pp(11) = premium_pp() * (1 + i_cr) on a contract issued at
t = 0. Do not additionally compound daily; the discretization affects only the
placement of interest within a month.
On a point issued at t = 0 the two clocks coincide and this model computes what
MYGA_US_S computes: every cell the two share agrees at every argument
MYGA_US_S evaluates in its sweep, but for five whose meaning changed —
pols_if_init, now the count already in force at the valuation date; model_point,
a row of another table; av_pp_init and mgsv_pp_init, now the account value and
the floor in force entering month 0, whose issue values are credited in the issue month
instead; and result_pols, which gains the month’s new business. That is how
MYGA_US_S’s goldens on its new-business points carry over, each on a cell its
sweep reaches — the worked example, both surrender traces, the roll-forwards — and
tests/test_model_conventions.py asserts it cell by cell; the statutory nonforfeiture
rate, which no report reads, is compared on the restated rows of
tests/test_fixed_deferred_annuity_us_sec.py. On a point in force the projection is
MYGA_US_S’s from the month
the point is valued at, month for month, its expenses apart, which are in valuation-date
dollars, and tests/test_fixed_deferred_annuity_us_sec.py asserts that.
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,
pols_new_biz(), before the month’s decrements. A point in force at the valuation
date opens with 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 t_entry(), the first month on the books, and
nothing is counted outside cover (is_active()): before issue every count, and so
every cash flow, is zero, and so is every value state. Inside the month the decrements
are MYGA_US_S’s, in the notes’ order, and pols_if_at names the count
between each: BEF_MORT after the annuitization elections, BEF_LAPSE after
deaths and AFT_DECR after surrenders, the notes’ end-of-month l(t).
The opening state
Each value state variable is a closing balance at the end of month t:
av_pp(t), mgsv_pp(t), prem_accum_gmir_pp(t), interest_credited_pp(t) and
tax_basis_pp(t). The value entering month t is the closing balance of month
t - 1, or, at t_entry(), the model point’s opening state — written inline as
av_pp(t - 1) if t > t_entry() else av_pp_init() wherever an opening balance is
read, 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 ten columns of its row, per contract, as the
contract stands at the start of month 0, before any month-0 event, each exactly what
MYGA_US_S carries into the month the point is valued at:
the account value, the Model #805 floor and
P_accum@GMIRentering month 0 (av_pp_init(),mgsv_pp_init(),prem_accum_gmir_pp_init()), the last two possibly negative;the interest credited from issue to the valuation date (
interest_credited_pp_init()), which themin_sc_interestcap reads, and to the anniversary that opened the contract year under way (interest_credited_pp_prev_anniv_init()), which next year’s interest-only allowance reads;the free-withdrawal allowance of the contract year under way (
free_wd_allow_init()), read on a valuation on an anniversary, and the part of it unused (free_wd_remain_init()), read on any other;the IRC 72 investment in the contract (
tax_basis_pp_init());the declared rate and the MVA reference yield
i0in force entering month 0 (credit_rate_init(),mva_ref_yield_locked_init()), read wherever the redeclaration or the start of the guarantee period in force precedes the valuation date.
For a point issued at or after the valuation date every one of them is 0 but
tax_basis_pp_init(), which is then the basis at issue, as MYGA_US_S takes
it. The issue values are computed by MYGA_US_S’s rules, in the issue month: the
premium credited, P (1 - load), through prem_to_av_pp(), and 87.5% of gross
consideration to the floor through prem_to_mgsv_pp() [R1 4.A(2)].
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-contract amounts, *_at(t, timing) for a quantity read at a point inside the
month. 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.
duration_mth_init, the policy months completed at the valuation date, takes
UL_US_S’s name. A column of the opening state is the cell it opens with _init
added, av_pp_init for av_pp(), and so is free_wd_allow_init, which
free_wd_allow() returns for the contract year under way; a balance at the
anniversary on or before the valuation date adds _prev_anniv_init instead,
interest_credited_pp_prev_anniv_init. t_entry and maturity_mth are this
model’s own, and surr_charge_age_cap_at is the age-keyed reader the library spells
_at, as WholeLife_US_S’s mort_rate_guar_at, and so is mort_rate_at.
point_id is basiclife.BasicTerm_SC’s; scenario_number,
wd_schedule_number and mort_schedule are the rows of Data’s arrays a point
reads, and mva_term_years the whole years of mva_term. The is_* cells decode
the model point’s text columns into the flags the projection branches on, so that no
monthly cell compares a column’s text and none calls a label accessor
(renewal_architecture, free_wd_rule, mva_family, …), which is left to
reporting. No monthly cell compares text at all: MYGA_US_S’s timing and kind strings
and the schedule surr_charge_id() names are int codes here (Codes, below). The
technical notes use compact actuarial symbols instead.
The notes’ month index is this model’s duration_mth(t), so the notes’ t in the
left-hand column is duration_mth(t) throughout, but in the rows marked valuation
clock, where it is this model’s t. The mapping is:
Notes symbol |
Cells |
Meaning |
|---|---|---|
t |
duration_mth(t) |
The notes’ month index: completed policy months at the start of month t |
y = floor(t/12) + 1 |
policy_year(t) |
Contract year containing month t (1-based label) |
y - 1 = floor(t/12) |
duration(t) |
Completed contract years at the start of month t |
x |
age_at_entry |
Issue age (ANB) |
x + floor(t/12) |
age(t) |
Attained age in month t |
n |
guar_period |
Guarantee period in years |
(none) |
policy_term |
Years from issue to maturity_age |
12(100 - x) |
maturity_mth |
Policy month at which cover ends |
(none) |
duration_mth_init |
Completed policy months at the valuation date; -k if issued k months later |
(frame) |
proj_len |
Months from the valuation date to maturity; the frame ends at proj_len - 1 |
(none) |
t_entry |
First month on the books |
(none) |
is_active(t) |
Whether month t is inside cover |
(none) |
policy_count |
Contracts the model point stands for |
(renewal_architecture) |
is_rollover is_annual_redeclare |
Camp A or Camp B, decoded |
(free_wd_rule) |
is_pct_av is_interest_only |
The free-withdrawal rule, decoded |
(mva_family) |
is_linear_duration is_geometric is_declared_differential |
The MVA family, decoded |
(mva_cap_rule) |
is_cap_none is_cap_sym_sc is_cap_min_sc_interest is_cap_asym_sc_snfl is_cap_gmir_floor |
The MVA cap rule, decoded |
(mgsv_wd_convention) |
is_wd_gross is_wd_net_of_charges |
The floor’s deduction of a withdrawal, decoded |
P |
premium_pp |
Single purchase payment |
i_cr(t) |
credit_rate(t) |
Declared credited rate, eff. annual |
i_cr in force |
credit_rate_init |
Declared rate in force entering month 0 |
f(t) - 1 |
credit_rate_mth(t) |
Monthly credited rate |
(declaration month) |
redeclare_month(t) |
Policy month the rate in force was declared |
s_ren |
renewal_spread |
Renewal declaration spread (Reference) |
i_nf |
mgsv_rate |
GMSV accumulation rate (2.80%) |
g - 1 |
mgsv_rate_mth |
Monthly GMSV rate |
i_stat |
mgsv_rate_statutory(cmt5) |
Model #805 indexed rate |
GMIR |
gmir |
Guaranteed minimum interest rate |
MR(t) |
market_rate(t) |
Market competitor rate, valuation clock |
AV(t) |
av_pp(t) |
Account value at end of month t (closing balance) |
AV(t-1), AV’(t), AV(t) |
av_pp_at(t, timing) |
BEF_WD / BEF_INV / EOM; BEF_WD holds the premium in the issue month |
AV(-1) |
av_pp_init |
Account value entering month 0 |
(premium credited) |
prem_to_av_pp(t) |
Premium credited to the account value, in the issue month |
l(t) x AV(t) |
av_at(t, timing) |
In-force weighted account value |
(interest credited) |
inv_income_pp(t) |
Interest credited in month t |
(cumulative interest) |
interest_credited_pp(t) |
Interest credited to date |
(interest to date) |
interest_credited_pp_init |
Interest credited before the valuation date |
(I at anniversary) |
interest_credited_pp_prev_anniv_init |
Interest credited to the anniversary opening the year under way |
MGSV(t) |
mgsv_pp(t) |
Model #805 floor at end of month t |
MGSV(-1) |
mgsv_pp_init |
Model #805 floor entering month 0 |
0.875 x P |
prem_to_mgsv_pp(t) |
The consideration the floor opens with, in the issue month |
c(t) |
mgsv_charge_pp(t) |
Monthly slice of the contract charge |
d(t) |
mgsv_wd_deduct_pp(t) |
Withdrawal deducted from the floor |
FWB(y) |
free_wd_base(y) |
Free-withdrawal base fixed at the start of year y |
0.10 x FWB(y) |
free_wd_allow(y) |
Allowance for contract year y |
(year’s allowance) |
free_wd_allow_init |
Allowance of the contract year under way at the valuation date |
FW(t) |
free_wd_avail(t) |
Unused allowance at BOM of month t |
(FW after W(t)) |
free_wd_remain(t) |
Unused allowance after the withdrawal |
(FW carried) |
free_wd_remain_init |
Unused allowance carried into month 0 |
W(t) |
wd_pp(t) |
Gross amount removed from the AV |
(scheduled W) |
wd_scheduled_pp(t) |
Withdrawal scheduled at the policy month of t |
(free part of W) |
wd_free_pp(t) |
Free portion of W(t) |
E(t) on a withdrawal |
wd_excess_pp(t) |
Withdrawal exposed to charge and MVA |
E(t) on a surrender |
surr_excess_pp(t) |
Surrender exposed to charge and MVA |
sc(y) |
surr_charge_rate(t) |
Surrender charge rate in force |
sc_clock(t) |
surr_charge_year(t) |
Year within the current schedule |
(schedule key) |
surr_charge_id(t) |
INITIAL / RENEWAL / NONE |
(age cap) |
surr_charge_age_cap(t) |
Attained-age cap on the charge in month t |
(age cap by age) |
surr_charge_age_cap_at(a) |
The same, keyed by attained age |
C(t) |
surr_charge_pp(t) |
Charge on a full surrender |
C(t) on a withdrawal |
wd_charge_pp(t) |
Charge on a partial withdrawal |
mu(t) |
mva_rate(t) |
MVA rate, signed |
M(t) |
mva_pp(t) |
Capped MVA on a full surrender |
M(t) on a withdrawal |
wd_mva_pp(t) |
Capped MVA on a partial withdrawal |
T(t) |
mva_term(t) |
MVA duration in years |
(whole years of T) |
mva_term_years(t) |
Its whole years, an int |
(period index) |
gp_index(t) |
Guarantee period containing month t |
(period start) |
gp_start_month(t) |
First policy month of that period |
i0 |
mva_ref_yield_locked(t) |
Reference yield locked at period start |
i0 in force |
mva_ref_yield_locked_init |
Reference yield locked for the period in force entering month 0 |
it |
mva_ref_yield(t) |
Reference yield at month t, valuation clock |
Phi(t) |
mva_rate(t) |
Geometric MVA factor, inline |
F_s |
mva_duration_factor(t) |
Declared-differential duration factor |
(term rounded up) |
mva_ref_term_years(tau) |
Whole-year maturity of the distribution yield |
prem_accum_gmir_pp(t) |
Premium less prior withdrawals at the GMIR |
|
(P_accum entering) |
prem_accum_gmir_pp_init |
P_accum@GMIR entering month 0 |
s_adm |
mva_admin_spread |
Geometric MVA expense adder (Reference) |
SV(t) |
surr_value_pp(t) |
Gross surrender value before the floor |
SB(t) |
surr_benefit_pp(t) |
Surrender benefit paid |
gp_end(t) |
gp_end(t) |
Months left in the guarantee period |
(the 30-day window) |
in_gp_window(t) |
True in the guarantee-period- end window |
basis(t) |
tax_basis_pp(t) |
IRC 72 investment in the contract |
basis(-1) |
tax_basis_pp_init |
Investment in the contract entering month 0, or at issue |
(taxable part of W) |
taxable_wd_pp(t) |
Income-first taxable amount |
l(t-1) |
pols_if(t) |
In force weighting month t: after new business, before decrements |
(opening l) |
pols_if_init |
In force at the valuation date; 0 for new business |
(none) |
pols_new_biz(t) |
Contracts issued in month t |
l(t) |
pols_if_at(t, AFT_DECR) |
In force at the end of month t |
(intra-month l) |
pols_if_at(t, timing) |
BEF_NB / BEF_DECR / BEF_MORT / BEF_LAPSE / AFT_DECR |
q(t) |
mort_rate_mth(t) |
Monthly mortality rate |
(annual q_x) |
mort_rate(t) |
Annual mortality at the attained age |
(q_x by age) |
mort_rate_at(a) |
The same, keyed by attained age |
(label) |
point_id |
The model point’s label |
(table rows) |
scenario_number wd_schedule_number mort_schedule |
Its scenario’s row Its programme’s row Its sex’s row |
w(t) |
lapse_rate_mth(t) |
Monthly total surrender rate |
w_annual(t) |
lapse_rate(t) |
Annual total surrender rate |
Base(y) |
lapse_rate_base(t) |
Prescribed base lapse by contract year |
G |
gmir_factor |
VM-22 GMIR factor |
Market(t) |
lapse_dyn_market(t) |
Dynamic-lapse market term |
Rate(t) |
lapse_dyn_rate(t) |
Dynamic-lapse rate term |
Phi_MVA(t) |
mva_lapse_factor_at(t) |
MVA factor gating the dynamic term |
BF |
lapse_buffer |
Dynamic-lapse buffer factor (Reference) |
X |
lapse_dyn_exponent(t) |
Dynamic-lapse exponent |
a(t) |
annuitization_rate(t) |
Monthly annuitization election rate |
l a |
pols_annuitization(t) |
Annuitization elections |
l (1-a) q |
pols_death(t) |
Deaths |
l (1-a)(1-q) w |
pols_lapse(t) |
Full surrenders |
(none) |
pols_maturity(t) |
Deemed-maturity annuitizations |
P on new business |
premiums(t) |
Premium income, in the issue month |
(premium credited) |
prem_to_av(t) |
Premium credited, in-force weighted |
W + M - C |
withdrawals(t) |
Withdrawal payments |
(ledger benefit lines) |
claims(t, kind) |
Benefit outgo by kind |
(benefit per contract) |
claim_pp(t, kind) |
Benefit per contract by kind |
(AV released) |
claims_from_av(t, kind) |
Account value released by a claim |
(paid above AV) |
claims_over_av(t, kind) |
Benefit paid above the account value |
0.02 x P |
commissions(t) |
Acquisition commission |
50/12 x 1.025^(t//12) |
expenses(t) |
Maintenance expense, valuation clock, plus acquisition on new business |
1.025^(t//12) |
inflation_factor(t) |
Expense inflation, valuation clock |
premium tax |
premium_taxes(t) |
Premium tax |
NetCF(t) |
net_cf(t) |
Net cash flow |
(none) |
result_pols() |
The counts behind result_cf |
Six names needed care, and all six are collisions the notes themselves carry.
d(t) in these notes is the withdrawal deducted from the Model #805 floor in
processing step 7, not deaths as in Term_US_S; it becomes
mgsv_wd_deduct_pp(), leaving pols_death() unambiguous. c(t) is the monthly
slice of the annual contract charge, not conversions, and becomes mgsv_charge_pp().
E(t) names two different currency bases — the excess of a withdrawal over the free
allowance and the excess of the whole account value over it at a full surrender — which
wd_excess_pp() and surr_excess_pp() separate; the same symbol is expenses in
Term_US_S, which here is expenses(). X is the dynamic-lapse exponent here
and the premium tax in Term_US_S, split into lapse_dyn_exponent() and
premium_taxes(). T(t) is the MVA duration in years while t counts
months, so it becomes mva_term(). And the floor itself carries three labels in the
sources — MGSV in this library, “GMSV” in the specimen [S11], “MGV” in the fixed-indexed
annuity notes — one concept, named mgsv_pp() throughout.
Two further names carry a library-wide convention that differs from the notes’ own indexing, and in both cases the notes’ quantity survives under a second name rather than being dropped.
pols_if() is the count in force at the start of month t, after the month’s
new business and before its decrements, pols_if_at(t, BEF_DECR), matching
Term_US_S and savings.CashValue_SE, and it is the weight applied to that same
month’s cash flows — withdrawals(), expenses() and the pols_if column of
result_cf() reconcile row by row. The notes’ end-of-month l(t) is unchanged and
unmoved; it is read as pols_if_at(t, AFT_DECR), and pols_if_at(t + 1, BEF_NB)
== pols_if_at(t, AFT_DECR) in every month but the last covered one,
duration_mth(t) = maturity_mth() - 1, where pols_maturity() empties the block.
lapse_rate() is the annual total surrender rate and lapse_rate_mth() the
monthly one, matching the mort_rate() / mort_rate_mth() pair and the eight
other models that spell it that way. The notes write the monthly rate w(t) and the
annual rate w_annual(t), so the pairing here is the notes’ own — only the suffixes
move.
Three rows of the table above are References, not Cells, because the notes give each
as a single assumption number rather than a function of t: s_ren is
renewal_spread, the spread in i_cr^ren(t) = max(GMIR, MR(t) - s_ren) (0.00% on the
base run, 1.00% in the notes’ scenario [std]); BF is lapse_buffer, the 50 bp
band inside which the dynamic-lapse response is exactly zero; and s_adm is
mva_admin_spread, the 25 bp administrative-expense adder in the geometric MVA’s
denominator [S4], which the other registered contract sets to 0 [S3]. Rebasing any of
the three is an assignment to the Reference, made before the model computes anything,
with no formula change. P_accum@GMIR, by contrast, is a recursion and so a Cells:
prem_accum_gmir_pp() is the level the gmir_floor cap holds AV + M above
[S13].
Two quantities the notes list as model point attributes are fixed at issue by a rule the
notes also state, and are computed by that rule, in the issue month: av_initial is
premium_pp() * (1 - load_prem_rate) with no front-end load [S5][S10][S16], credited
through prem_to_av_pp(), and mgsv_initial is net_consideration_ratio *
premium_pp() — 87.5% of gross consideration [R1 4.A(2)] — through
prem_to_mgsv_pp(). av_pp_init() and mgsv_pp_init(), the names
MYGA_US_S gives those issue values, are here the account value and the floor in
force entering month 0, 0 on new business. The notes’ tax_basis_initial genuinely
varies with tax status, so it is a model point column, tax_basis_pp_init: the basis at
issue for a contract not yet in force, the basis entering month 0 for one in force.
Timing arguments
Account value, following CashValue_SE’s av_pp_at:
BEF_WDAV(t-1), at the start of monthtbefore the elective withdrawal: the account value entering the frame,av_pp_init(), att_entry()for a point in force, the previous month’s closing balance after, and in the issue month the premium credited,prem_to_av_pp(), on top.BEF_INVAV'(t), after the withdrawal and after annuitization elections, before crediting.EOMAV(t), after crediting. Equal toav_pp(), the closing balance of montht.
Policy counts, following CashValue_SE’s pols_if_at and basiclife.BasicTerm_SE’s
BEF_NB:
BEF_NBthe count carried in from month
t - 1, before montht’s new business:pols_if_init()att_entry(), zero outside cover.BEF_DECRl(t-1), in force at the start of montht, after its new business. Equal topols_if().BEF_MORTafter annuitization elections,
l(t-1)(1 - a(t)).BEF_LAPSEafter deaths,
l(t-1)(1 - a(t))(1 - q(t)).AFT_DECRafter surrenders,
l(t)— the notes’ end-of-month in-force.
BEF_NB is the one timing running in force adds. basiclife.BasicTerm_SE’s
"BEF_MAT", the count at the start of a month before its maturities, is not adopted:
this product has no timing of that name, and its contracts mature at the end of the last
covered month, as the S goldens have it.
Benefit kind arguments are DEATH, LAPSE, ANNUITIZATION and
MATURITY, and ALL for the total of claims() and claims_over_av(). Any
other value of any of these raises ValueError.
pols_maturity and the projection horizon
The technical notes state no projection horizon: a MYGA under the rollover
architecture renews indefinitely, and the notes’ own base-lapse pattern is written as a
repeating five-year cycle with no terminal date. The model runs to the contract
anniversary at attained age maturity_age = 100 [std] — the last attained age in
the sourced cap band on the renewal surrender charge, which the notes tabulate as 4% at
94, 3% at 95, 2% at 96, 1% at 97 and 0% at 98-100 [S1][S2]. The cap reaches zero at 98;
100 is where the sourced band stops, and it is past the statutory deemed maturity date of
Model #805 section 8 [R1]. That anniversary is policy month maturity_mth(). The
survivors there are annuitized out through pols_maturity(), zero in every month but
the last covered one, duration_mth(t) = maturity_mth() - 1, which is
t = proj_len() - 1, so that:
pols_if(t) - pols_if_at(t + 1, BEF_NB) = pols_annuitization(t) + pols_death(t)
+ pols_lapse(t) + pols_maturity(t)
holds for every t — the start-of-month count opens the row, the four exits are taken
during it and the next month opens on what is left, before its own new business.
Including the last covered month, where the block would otherwise appear to lose lives
with no cause. The name follows BasicTerm_S.pols_maturity and the construction follows
Term_US_S.
Codes
What MYGA_US_S spells as text, a timing, a kind, a scenario column or a
surrender charge schedule, 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_WD), claims(t, DEATH).
Reference |
Value |
Meaning |
|---|---|---|
BEF_NB |
0 |
|
BEF_DECR |
1 |
|
BEF_MORT |
2 |
|
BEF_LAPSE |
3 |
|
AFT_DECR |
4 |
|
BEF_WD |
5 |
|
BEF_INV |
6 |
|
EOM |
7 |
|
DEATH |
0 |
the claim cells: the death claim |
LAPSE |
1 |
the claim cells: the surrender claim |
ANNUITIZATION |
2 |
the claim cells: the annuitization election |
MATURITY |
3 |
the claim cells: the deemed maturity |
ALL |
4 |
|
MVA_REF_YIELD |
0 |
|
MARKET_RATE |
1 |
|
NONE |
0 |
|
INITIAL |
1 |
|
RENEWAL |
2 |
|
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 others, then the account value’s, each family in the
order of its instants within the month. 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 result_cf’s order, which is
the order MYGA_US_S adds them in its total, and ALL, MYGA_US_S’s
kind=None, after them; the claim cells but claims() and claims_over_av()
refuse it, ValueError("invalid kind"). NONE, INITIAL and RENEWAL are also
the rows of Data.surr_charge_array, which holds the two schedules there. A code a
cell takes indexes that cell’s cache, a C array of eight codes a month for each of the
ten 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, and a code a cell does not
take but below 8 is refused inside the cache. They are References, not cells, so the
symbol map does not list them. Every other Reference is named in lower case,
issue_age_min and issue_age_max among them, the product’s issue ages, the first
of which, with maturity_age, the compiled model’s caches are sized from
(proj_len()).
Reporting cells
model_point(), the label accessors policy_id(), sex(),
tax_status(), mgsv_wd_convention(), renewal_architecture(),
free_wd_rule(), mva_family(), mva_cap_rule(), scenario_id() and
wd_schedule_id(), the reports result_cf(), result_pols() and
result_av(), and the checks check_av_roll_fwd() and
check_pols_roll_fwd() are written for a reader and for the comparison with
MYGA_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 and the rows 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: Data accepts, and the model projects, a point whose
tax_status or policy_id is blank or a number, which no cell reads, or whose
sex, scenario_id or wd_schedule_id is a number, where its table’s keys are
numbers, and the compiled accessor returns what modelx returns, NaN or an int. 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.
Three cells of float parameters compile with C signatures and dict caches, their
bodies Python, the engine cells mgsv_rate_statutory(),
mgsv_rate_is_compliant() and mva_ref_term_years(): MYGA_US_S’s own,
math included, kept for a user checking a contract rate against the statute and for
the comparison with MYGA_US_S. No projection cell calls them, and a cell keyed
by a float compiles with a Python dict for a cache, so the registry admits them by name.
Compiled, mva_ref_term_years() returns a C long long, so a term below
-2**63, outside any term, overflows there, where modelx returns Python’s int. The
two others of MYGA_US_S’s float-parameter cells, mva_pp_on and
mva_factor_geometric, which the projection does call, are written inline in the cells
that call them, mva_pp(), wd_mva_pp() and mva_rate().
Cells Descriptions#
- model_point()[source]#
The selected model point, its row of
model_point_table_sec.csv, as a Series.Row
idxof 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 ownDatavector instead.
- point_id()[source]#
The label of the selected model point, its
point_id, fromData.point_id.Projectionis indexed by position,idx, asbasiclife.BasicTerm_SCis; the label is what a reader finds in the table, so every refusal names it.
- policy_id()[source]#
The contract identifier of the selected model point.
A reporting cell (the Space docstring), which no projection cell reads.
- age_at_entry()[source]#
The issue age (ANB) of the selected model point.
The age at issue, not at the valuation date:
age(0)is the attained age then. FromData.age_at_entry, which holds the column to a whole number of years below2**53in size.
- sex()[source]#
The sex of the selected model point, M or F.
A reporting cell (the Space docstring):
Datajoins the mortality table by it, throughmort_schedule(), and no projection cell reads it here.
- tax_status()[source]#
Tax status of the contract: NQ, IRA, Roth or inherited.
Reported only, a reporting cell (the Space docstring). The base run is non-qualified [std]; no RMD module is implemented.
P: the single purchase payment per contract.
- policy_count()[source]#
The number of contracts the model point stands for, its
policy_countcolumn.A point in force at the valuation date counts the contracts in force then, before any month-0 event; any other point counts the contracts it issues. Either way the count enters the projection once: as
pols_if_init()for the first, aspols_new_biz()in the issue month for the second. Every per-contract value — the account value, the floor, the allowance, the basis, the opening state — is the same whatever the count, and every cash flow is a per-contract amount weighted by it.
- pols_if_init()[source]#
Contracts in force at the valuation date, before any month-0 event.
policy_count()for a point already in force att = 0(duration_mth_init() > 0), and 0 for one issued at or after it, whose contracts enter throughpols_new_biz()in the issue month instead, as inbasiclife.BasicTerm_SE. So on a point issued att = 0this is 0, andpols_if(0)is the issued count.MYGA_US_S’s cell of the name is the notes’l(t-1)att = 0, the count at issue; in both models their end-of-monthl(t)ispols_if_at(t, AFT_DECR).
- guar_period()[source]#
n: the guarantee period in years; the surrender charge and MVA periods equal it.
- declared_rate_initial()[source]#
The declared credited rate guaranteed for the initial term, 4.45% p.a. [S11].
- gmir()[source]#
The guaranteed minimum interest rate, 0.25% p.a. [S11].
A floor on any declared rate.
- mgsv_rate()[source]#
i_nf: the contract GMSV accumulation rate, 2.80% p.a. [S11].
The Model #805 floor accretes at this rate. It must be at least the statutory indexed rate
mgsv_rate_statutory(); crediting the floor at more is permitted and simply produces a higher floor [R1 4.B].
- mgsv_annual_charge()[source]#
The annual contract charge deducted from the Model #805 floor.
$0 representative [S11]; the statutory maximum is $50 p.a. [R1 4.A].
- mgsv_wd_convention()[source]#
How a withdrawal reduces the Model #805 floor:
grossornet_of_charges.gross[S11] deducts W(t) itself;net_of_charges[S9] deducts the cash actually paid, W(t) + M(t) - C(t), keeping the floor higher. Both are live in the market and the difference compounds at i_nf for the rest of the contract. A reporting cell (the Space docstring):Datadecodes the column intois_wd_gross()andis_wd_net_of_charges(), and no projection cell reads it here.
- is_wd_gross()[source]#
Whether the floor deducts each withdrawal gross,
mgsv_wd_conventiongross.A decode of the model point’s column, made by
Dataonce for the table, as eachis_*cell’s is, so that the projection branches on a flag and no projection cell compares the column’s text or calls the label accessor,mgsv_wd_convention(), which is left to reporting.Data.is_wd_grosscompares the text exactly, asMYGA_US_Sdoes, soGrossor `` gross`` is no flag.mgsv_wd_deduct_pp()reads it.
- is_wd_net_of_charges()[source]#
Whether the floor deducts the cash paid,
mgsv_wd_conventionnet_of_charges.The other decode of the column (
is_wd_gross()). A value that is neither raises inmgsv_wd_deduct_pp(), as inMYGA_US_S.
- renewal_architecture()[source]#
rollover(Camp A) orannual_redeclare(Camp B).rolloverstarts a fresh guarantee period, surrender charge schedule and MVA period at each boundary [S1] (no MVA on that form) [S2] [S5] [S11], so the shock lapse repeats every n years.annual_redeclareredeclares the rate each anniversary with no further surrender charge and no MVA [S13], so the shock happens once. A reporting cell (the Space docstring), decoded byDataintois_rollover()andis_annual_redeclare().
- is_rollover()[source]#
Whether the contract renews under
rollover, Camp A.A decode of the
renewal_architecturecolumn (is_wd_gross()), read whereMYGA_US_Sasks whether the architecture isrollover:redeclare_month()andlapse_rate_base().
- is_annual_redeclare()[source]#
Whether the contract renews under
annual_redeclare, Camp B.A decode of the
renewal_architecturecolumn (is_wd_gross()), read whereMYGA_US_Sasks whether the architecture isannual_redeclare:in_gp_window(),surr_charge_id()andmva_term(). Each cell keeps the questionMYGA_US_Sasks, so a value that is neither is answered as there.
- free_wd_rule()[source]#
pct_avorinterest_only.pct_av[S10] is the representative 10%-of-base allowance;interest_only[S5][S6] is the prior contract year’s credited interest. The notes’ third value,greatest_of[S13], is not implemented: no formula is given for it. A reporting cell (the Space docstring), decoded byDataintois_pct_av()andis_interest_only().
- is_pct_av()[source]#
Whether the free-withdrawal allowance is
pct_av, a percentage of the base.A decode of the
free_wd_rulecolumn (is_wd_gross()), read byfree_wd_allow().
- is_interest_only()[source]#
Whether the free-withdrawal allowance is
interest_only, last year’s interest.A decode of the
free_wd_rulecolumn (is_wd_gross()), read byfree_wd_allow(), which raises on a rule that is neither, asMYGA_US_Sdoes.
- free_wd_mva_exempt()[source]#
Whether the free allowance is exempt from the surrender charge and the MVA.
True is the retail MYGA convention [std] [S8][S11] and gives
E(t) = AV(t) - FW(t). False is the registered-contract convention [S3][S4] and givesE(t) = AV(t), collapsing the surrender benefit to the multiplicative formmax(AV(t) x (1 + mu(t) - sc(y)), MGSV(t)). The notes apply the flag to both the charge and the adjustment; in the market it strictly concerns the adjustment.From
Data.free_wd_mva_exempt, an int64 vector holdingMYGA_US_S’sbool()of each value, so a blank, read as NaN, and any text are True, as there.
- mva_family()[source]#
linear_duration,geometricordeclared_differential. All implemented.A reporting cell (the Space docstring), decoded by
Dataintois_linear_duration(),is_geometric()andis_declared_differential().
- is_linear_duration()[source]#
Whether the MVA is the
linear_durationfamily.One of three decodes of the
mva_familycolumn (is_wd_gross()), read bymva_rate(), which raises on a family that is none of them, asMYGA_US_Sdoes.
- is_geometric()[source]#
Whether the MVA is the
geometricfamily.A decode of the
mva_familycolumn (is_linear_duration()).
- is_declared_differential()[source]#
Whether the MVA is the
declared_differentialfamily.A decode of the
mva_familycolumn (is_linear_duration()).
- mva_cap_rule()[source]#
sym_sc,min_sc_interest,asym_sc_snfl,gmir_floorornone.The cap, not the formula family, is the largest cross-carrier divergence in the source set, so it is a first-class model parameter. See
mva_pp(). A reporting cell (the Space docstring), decoded byDatainto the fiveis_cap_*flags.
- is_cap_none()[source]#
Whether the MVA is uncapped,
mva_cap_rulenone.One of five decodes of the
mva_cap_rulecolumn (is_wd_gross()), read bymva_pp()andwd_mva_pp(), which raise on a rule that is none of them, asMYGA_US_S’smva_pp_ondoes.
- is_cap_sym_sc()[source]#
Whether the MVA cap is
sym_sc, the surrender charge both ways.A decode of the
mva_cap_rulecolumn (is_cap_none()).
- is_cap_min_sc_interest()[source]#
Whether the MVA cap is
min_sc_interest: the charge or the interest, the lesser.A decode of the
mva_cap_rulecolumn (is_cap_none()).
- is_cap_asym_sc_snfl()[source]#
Whether the MVA cap is
asym_sc_snfl, the charge on the upside alone.A decode of the
mva_cap_rulecolumn (is_cap_none()).
- is_cap_gmir_floor()[source]#
Whether the MVA cap is
gmir_floor,AV + Mheld atP_accumor above.A decode of the
mva_cap_rulecolumn (is_cap_none()).
- mva_ref_yield_at_issue()[source]#
i0 at issue: the MVA reference yield locked for the initial period.
5.00% [std], fixed at issue for the whole initial term.
Premium tax deducted from the contract, 0% [std] [S3][S16].
- tax_basis_pp_init()[source]#
The IRC 72 investment in the contract at the start of month
t_entry()[R6].The
tax_basis_pp_initcolumn,MYGA_US_S’stax_basis_initialunder the name of the cell that reads it. For a point in force it is the basis entering month 0, before any month-0 event: the close of policy monthduration_mth_init() - 1, whatMYGA_US_Scarries into that month as thetax_basis_ppof the month before. For a point issued at or after the valuation date it is the basis at issue, which varies with tax status, asMYGA_US_Stakes it: the premium on every shipped point, all of them non-qualified. So it is the one opening-state column that is not 0 on new business. The notes’basis(t)is the end-of-month value, so this isbasis(t-1)att_entry(), nottax_basis_pp(t_entry()).
- prem_accum_gmir_pp_init()[source]#
P_accum@GMIR entering month 0, per contract, the
prem_accum_gmir_pp_initcolumn.The premium less prior withdrawals accumulated at the GMIR to the close of policy month
duration_mth_init() - 1, whatMYGA_US_Scarries into that month as theprem_accum_gmir_pp()of the month before. It opensprem_accum_gmir_pp()att_entry(), and so the level thegmir_floorcap holdsAV + Mabove in every month [S13]. It may be negative: withdrawals are deducted from it and nothing floors it, in either model. Zero for a point not yet in force, whose premium enters it in the issue month.
- interest_credited_pp_init()[source]#
Interest credited from issue to the valuation date, per contract.
The
interest_credited_pp_initcolumn: cumulative interest to the close of policy monthduration_mth_init() - 1, whatMYGA_US_Scarries into that month as theinterest_credited_pp()of the month before. It opensinterest_credited_pp()att_entry(), which themin_sc_interestMVA cap reads in every month — the adjustment is limited to the lesser of the surrender charge and the interest credited to date [S8][S9] — and the interest-only allowance reads at each anniversary. Zero for a point not yet in force.
- interest_credited_pp_prev_anniv_init()[source]#
Interest credited from issue to the anniversary opening the contract year under way.
The
interest_credited_pp_prev_anniv_initcolumn, per contract: cumulative interest to the close of policy month12 * duration(0) - 1, the anniversary on or before the valuation date. The interest-only allowance of a contract year is the interest credited over the year before it [S5][S6], so the allowance of the year after the one under way is the interest from this anniversary to the next, andfree_wd_allow()reads it there. It isinterest_credited_pp_init()on a point valued on an anniversary, the same instant, whichDatachecks, and 0 in the first contract year, which opened at issue with nothing credited.prev_annivis the anniversary that opened the year. Zero for a point not yet in force.
- free_wd_allow_init()[source]#
The free-withdrawal allowance of the contract year under way at the valuation date.
The
free_wd_allow_initcolumn, per contract, named for the cell that returns it:free_wd_allow()gives it for the contract year in force att = 0, the one opened by the anniversary on or before the valuation date. Underpct_avit isfree_wd_rate x FWB, the rate times the account value at that anniversary [S10]; underinterest_onlyit is the interest credited over the contract year before [S5][S6], which no single anniversary value gives, so the allowance itself is carried rather than the base it was fixed on.The projection reads it on a valuation on an anniversary only,
duration_mth_init()a multiple of 12, where month 0 opens the year andfree_wd_avail()resets to it; thereDataholds it, to a cent, tofree_wd_ratetimes the account value underpct_av, and underinterest_onlyto at most the interest credited to the anniversary, and in the second contract year to exactly that, the first year’s. On any other valuation the year’s remainder,free_wd_remain_init(), carries the year, and this column is read only byData’s check that the remainder does not exceed it. In the first contract year it is the issue allowance,free_wd_rate x premiumunderpct_avand 0 underinterest_only, whichDatachecks. Zero for a point not yet in force, which takes its allowance from the rule at each anniversary.
- free_wd_remain_init()[source]#
The unused free-withdrawal allowance carried into month 0, per contract.
The
free_wd_remain_initcolumn:free_wd_remain()at the close of policy monthduration_mth_init() - 1, the year’s allowance less what the year’s withdrawals have already used.free_wd_avail()opens from it att = 0on a point valued off an anniversary, and what a surrender at the end of month 0 may still shelter is that less month 0’s free withdrawal,free_wd_remain()of month 0. On a valuation on an anniversary month 0 opens a new contract year, the allowance resets tofree_wd_allow_init(), and last year’s remainder lapses unread, the allowance being non-cumulative [S4][S16].Datarefuses a remainder above the year’s allowance off an anniversary. Zero for a point not yet in force.It takes no
_ytdin its name, though it belongs to the contract year: it is not an accumulator restarting each year but the remainder of the allowance it is named for,free_wd_allow(), an annual quantity, which each anniversary resets to that year’s allowance.
- credit_rate_init()[source]#
i_cr in force entering month 0: the declared rate credited in the month before.
The
credit_rate_initcolumn:credit_rate()in policy monthduration_mth_init() - 1. A declared rate is fixed when it is declared, at issue for the initial term [S11] and at each redeclaration after it, so for a point valued inside a renewal period whose redeclaration preceded the valuation date it is a fact of the past, which this column carries:credit_rate()returns it wherever the declaration in force at monthtwas made beforet_entry(). A redeclaration at month 0 itself, a valuation on a renewal date, reads the scenario att = 0, and the column, the rate entering that month, is then unread. It equals the initial declared rate entering any month of the initial term, the first renewal month included, and is the GMIR or more after it;Datachecks both. Zero for a point not yet in force.
- mva_ref_yield_locked_init()[source]#
i0 in force entering month 0: the MVA reference yield locked for the period in force.
The
mva_ref_yield_locked_initcolumn, per contract:mva_ref_yield_locked()in policy monthduration_mth_init() - 1.i0is locked at the start of each guarantee period — the issue value for the initial term, the prevailing reference yield at each renewal underrollover[S2][S11] — so for a point valued inside a renewal period that started before the valuation date it is a fact of the past, whichmva_ref_yield_locked()returns wherever the period in force at monthtstarted beforet_entry(). A period starting at month 0 itself locks at the scenario’s yield att = 0. It equalsmva_ref_yield_at_issueentering any month of the initial term, whichDatachecks. Underannual_redeclareno MVA applies after the initial term, and the column is carried unread. Zero for a point not yet in force.
- scenario_id()[source]#
The rate scenario the model point runs on, a key into rate_scenario.csv.
A reporting cell (the Space docstring):
Datajoins the scenario by it, throughscenario_number(), and no projection cell reads it here.
- wd_schedule_id()[source]#
The withdrawal programme, a key into withdrawal_table.csv.
A reporting cell (the Space docstring):
Datajoins the programme by it, throughwd_schedule_number(), and no projection cell reads it here.
- scenario_number()[source]#
The point’s rate scenario, its row of the scenario arrays, from
Data.Data.scenario_numbernumbers the scenarios of rate_scenario.csv from 1 in the sorted order of their ids and gives each point the number of itsscenario_id, matched by value asMYGA_US_S’s.locmatches it.Datarefuses a point whose scenario the table lacks, so the number is 1 or more.scenario_rate()reads the arrays at it.
- wd_schedule_number()[source]#
The point’s withdrawal programme, its row of
Data.wd_amount_array.Numbered as
scenario_number()numbers the scenarios, from the programmes of withdrawal_table.csv;Datarefuses a programme the table lacks, so the number is 1 or more.wd_scheduled_pp()reads the array at it.
- mort_schedule()[source]#
The point’s sex, its row of
Data.mort_table_array.Numbered as
scenario_number()numbers the scenarios, from the sexes of mort_table.csv;Datarefuses a sex the table lacks, so the number is 1 or more.mort_rate_at()reads the array at it, andproj_len()its last age.
- maturity_mth()[source]#
The policy month at which cover ends:
12 * policy_term().The deemed maturity falls at the contract anniversary at attained age
maturity_age= 100 [std], so this is theduration_mthof the first month not covered, 480 at issue age 60, and the last covered month ismaturity_mth() - 1, the one ending at that anniversary. It isMYGA_US_S’s frame length, counted from issue on the policy clock;proj_len()counts from the valuation date instead.
- proj_len()[source]#
The number of months from the valuation date to the deemed maturity.
maturity_mth() - duration_mth_init(): 480 for the anchor cell issued att = 0, 468 for it in force 12 months, 1 for the Camp B point in its last covered month, and 495 for the anchor issued 15 months after the valuation date. The frame ist = 0, 1, ..., proj_len() - 1;proj_len()is its exclusive end and the row count ofresult_cf(), andproj_len() - 1is the last covered month, the one ending at the contract anniversary atmaturity_age.Four kinds of point have no frame the contract issues or the tables can project, and each raises here, naming the point, rather than projecting what the contract does not hold, in this order:
one issued below
issue_age_min, 0, the youngest issue ageproduct-spec.mdadmits.MYGA_US_Sprojects any age its tables rate, but the compiled model’s caches are sized from the contract (spec_sec.py): a younger point, whose frame and contract years run longer, would read past them;one issued above
issue_age_max, 85, the oldest issue ageproduct-spec.mdadmits. No cache is sized from it, since an older issue only shortens every frame, andMYGA_US_Sprojects such a point; it is refused as a contract the product does not issue, and set higher it projects as there;one at or past maturity at the valuation date, which an in-force extract should not carry;
one whose sex the mortality table rates only to an attained age below
maturity_age - 1, the last covered month’s, every issue age reaching that age in its last covered month.Datacannot check it,maturity_agebeing a Reference of this Space, so it checks the table’s last age by sex,Data.mort_age_lasts, here, whereMYGA_US_Sraises itsKeyErrorat the first month past the table. The shipped table runs to 120.
- duration_mth_init()[source]#
Completed policy months at the valuation date, the
duration_mthcolumn.The contract’s age in months at
t = 0: 12 for the anchor cell valued on its first anniversary, 30 for the interest-only point valued the month after its excess withdrawal, 0 for a contract issued at the valuation date, and -15 for one to be issued 15 months after it, whichDataadmits up tofuture_horizon_mthmonths ahead. It is read asbasiclife.BasicTerm_SEreads it, as a whole number whatever the column’s type, and is the one fact the policy clock takes from the model point.
- duration_mth(t)[source]#
Completed policy months at the start of month t, the policy clock.
duration_mth_init() + t:tcounts months from the valuation date andduration_mth(t)months from issue, and the two move together. A closed form, wherebasiclife.BasicTerm_SEadds one a month by recursion: the same numbers, without a call chain as long as the frame. Negative before issue. It is the technical notes’ month index,MYGA_US_S’st, and everything contractual reads it, throughduration(),policy_year(),age()andgp_index().
- t_entry()[source]#
The first month the contract is on the books:
max(0, -duration_mth_init()).0 for a point in force at the valuation date or issued at it,
kfor one issuedkmonths later. It is the base of every recursion:pols_if_at()opens there frompols_if_init(), the five value balances from the model point’s opening state, and the free-withdrawal carry fromfree_wd_remain_init(); a rate declared or a yield locked before it is read from the opening state too. No cell in cover reads a month before it.
- is_active(t)[source]#
Whether month t is inside cover: issued, and not yet at the deemed maturity.
0 <= duration_mth(t) < maturity_mth(). False before issue and from the month after the one ending at attained age 100. Outside cover every count is zero, and so every cash flow; so is every value state and every contractual rate, no count cell evaluates a rate there, and no table is read at a contract year or an attained age the contract does not have.
- policy_year(t)[source]#
y(t) = duration(t) + 1: the 1-based contract year containing month t.
A contractual label on the policy clock — the surrender charge schedule and the base lapse table are stated by contract year — never an index into the frame. It is 0 or less before issue, where nothing reads a schedule by it.
- duration(t)[source]#
Completed contract years at the start of month t,
duration_mth(t) // 12.0 throughout the first contract year, and negative before issue.
- gp_index(t)[source]#
The index of the guarantee period containing month t, on the policy clock.
duration_mth(t) // (12 n) + 1: 1 for policy months0 .. 12n - 1, the initial term, andk + 1in thek-th renewal period. Every renewal period isnyears, as the product has it, so the position in the period is derived from the policy clock alone. It is 0 or less before issue, where nothing reads it.
- gp_start_month(t)[source]#
The first policy month of the guarantee period containing month t.
12 n (gp_index(t) - 1): 0 for the initial term. A policy month, not a month of the frame:mva_ref_yield_locked()turns it into a valuation month, and reads the opening state where it falls beforet_entry().
- gp_end(t)[source]#
Months remaining in the current guarantee period at the end of month t.
12 n gp_index(t) - (duration_mth(t) + 1): 59 in policy month 0 and 0 in policy month12n - 1, the month that ends the period.
- in_gp_window(t)[source]#
True in the 30-day guarantee-period-end window [S1][S2][S5][S6].
The notes place the window in the month after a guarantee period closes, i.e. at
duration_mth(t) == 0 (mod 12n)withduration_mth(t) > 0, so for n = 5 it is policy months 60, 120, 180, … — the first month of each renewal period. In the window the full account value is available with no surrender charge and no MVA, and it is the only month in which annuitization is elected. Underannual_redeclarethere is exactly one window, at policy month12n, the month after the initial term. False outside cover: no month before issue is a window.
- redeclare_month(t)[source]#
The policy month at which the credited rate in force at month t was declared.
Policy month 0 for the initial term; under
rolloverthe first month of the current guarantee period, underannual_redeclarethe first month of the current contract year. A policy month, not a month of the frame:credit_rate()turns it into a valuation month, and reads the opening state where it falls beforet_entry().
- scenario_rate(t, name)[source]#
Step-function lookup of column
namein the model point’s rate scenario.Each row of rate_scenario.csv states the level that holds from its own valuation month
tuntil the next row of the same scenario, so a flat path is one row att = 0. The scenario is a path in calendar time, shared by every point of a block, so it is read attand never on the policy clock.nameis a code,MVA_REF_YIELDorMARKET_RATE(the Space docstring’s Codes), forMYGA_US_S’s column names; any other raisesValueError("invalid name").The table’s one reader.
Datafills each scenario’s step function intodata.mva_ref_yield_array()anddata.market_rate_array(), by scenario and valuation month, from the table checked, so the level attis one element, read at the point’sscenario_number(). Past the table’s last month,data.scenario_last_mth(), the last level holds, as the step function holds it. Before the scenario’s first month,data.scenario_first_mths(), it sets no level, and the read is refused, naming the point and the month, whereMYGA_US_S’smax()of no months raised.Datarefuses a point whose scenario is not in the table, or sets no level by the first month the point is on the books, and no cell reads the scenario before that month, so a projection never meets the refusal.
- market_rate(t)[source]#
MR(t): the market competitor rate driving renewal declarations and dynamic lapse.
VM-22 defines it for a 5 to 7 year guarantee period as the 7-year Treasury rate plus a 50% A / 50% AA spread less the pricing spread [R2 6.B.5]; the model takes it as an exogenous input because the index is a state-filed variable [std].
- mva_ref_yield(t)[source]#
it: the MVA reference yield at month t, from the scenario table [std].
The source design is Barclay’s US Credit Index with a state-varying formula [S8]; the model takes a scalar series rather than hard-coding an index.
- credit_rate(t)[source]#
i_cr(t): the declared credited rate in force, effective annual.
The initial declared rate for the whole initial term, policy months
0 .. 12n - 1[S11], then the renewal rulemax(GMIR, MR(m) - s_ren)[std] withmthe redeclaration month,redeclare_month()turned into a valuation month. A rate declared beforet_entry()is a fact of the past, the opening state’scredit_rate_init(); one declared at or after it is read from the scenario at its month, so a valuation on a renewal date takes the new rate from the scenario att = 0. The base run setsrenewal_spread = 0, so the credited rate equals the competitor rate and the dynamic lapse term is exactly zero. 0.0 outside cover.
- credit_rate_mth(t)[source]#
The monthly credited rate,
(1 + i_cr(t))^(1/12) - 1.Twelve of these factors reproduce the declared effective annual rate exactly, so the discretization moves interest only within a month. Do not compound daily as well.
- mgsv_rate_statutory(cmt5)[source]#
The Model #805 indexed nonforfeiture rate at a 5-year CMT level [R1 4.B].
max(0.0015, min(0.03, round(CMT5 to 1/20 of 1%) - 0.0125)). Two traps the notes call out: the floor is 15 basis points, not the widely repeated 1%; and the statute defines the minimum rate, it does not cap the contract rate — the contract must satisfymgsv_rate() >= mgsv_rate_statutory(cmt5), which is whatmgsv_rate_is_compliant()tests, not the reverse inequality.An engine cell,
MYGA_US_S’s formula,mathincluded: no projection cell calls it, so it compiles with a C signature and a dict cache, its body Python, admitted by name (the Space docstring’s Reporting cells), for a user checking a contract rate against the statute and for the comparison withMYGA_US_S. Amgsv_stat_stepof zero raisesZeroDivisionErrorwith Python’s message,float division by zero, tested here, asMYGA_US_Sraises it, which compiled division would word otherwise.
- mgsv_rate_is_compliant(cmt5)[source]#
True when the contract GMSV rate meets the statutory minimum [R1 4.B].
At a 5-year CMT level
cmt5:mgsv_rate() >= mgsv_rate_statutory(cmt5). An engine cell, asmgsv_rate_statutory()is, which it alone calls.
- av_pp_init()[source]#
AV(-1): the account value per contract entering month 0, the
av_pp_initcolumn.For a point in force, the closing balance of policy month
duration_mth_init() - 1, before any month-0 event: whatMYGA_US_Scarries into that month as theav_ppof the month before, and the opening balance ofav_pp()and ofav_pp_at(t, BEF_WD)att_entry(). Zero for a point not yet in force: its account value opens empty and takes the premium credited in the issue month,prem_to_av_pp().MYGA_US_S’s cell of the name computes that issue value,P (1 - load); here the rule moved to the issue month, where it stays a rule.
- prem_to_av_pp(t)[source]#
Premium credited to the account value per contract, in the issue month.
P x (1 - load_prem_rate), 100% of premium with no front-end load [S5][S10][S16], at BOM of the month withduration_mth(t) = 0, and 0 in every other month. It is the notes’av_initial, whichMYGA_US_Scomputes asav_pp_init(): fixed at issue by a rule the notes state, so computed by that rule rather than read.
- wd_scheduled_pp(t)[source]#
The gross withdrawal scheduled for month t in withdrawal_table.csv, else zero.
The amount at
(wd_schedule_id, duration_mth(t)): the table’stis a policy month, so a withdrawal programme stays where the contract has it, however old the contract is at the valuation date. The anchor’s $4,000 at policy month 12 falls att = 12on a contract issued att = 0and att = 0on one valued on its first anniversary. The table’s one reader:Dataholds each programme by policy month indata.wd_amount_array(), from the table checked, with 0.0 at a month the programme has no row,MYGA_US_S’s “a key that misses is no withdrawal”, and this reads it at the point’swd_schedule_number(). Past the table’s last month,data.wd_last_mth(), no programme withdraws.Datarefuses a programme the table lacks, so a month without a row is a month the programme takes nothing in, never a misspelt programme. 0.0 outside cover, where the policy month may be negative.
- wd_pp(t)[source]#
W(t): the gross amount removed from the account value at BOM of month t.
Gross by construction: a contract promising a stated net check needs a gross-up solve, which is not implemented [S3]. Two sources add up here — the amount scheduled in withdrawal_table.csv, and the free-withdrawal utilization variant
free_wd_util x FW(y)taken in the first month of each contract year, whereduration_mth(t)is a multiple of 12. Base run utilization is 0 [std], so only the scheduled withdrawals reach the account value: the anchor’s $4,000 at policy month 12 and point 5’s $20,000 at policy month 29, on the points made from them. 0.0 outside cover.
- av_pp(t)[source]#
AV(t): account value per contract at the end of month t (closing balance).
AV(t) = (AV(t-1) - W(t)) x (1 + i_cr(t))^(1/12)[S4][S5][S16], with the premium credited,prem_to_av_pp(), added to the opening balance in the issue month. The opening balanceAV(t-1)is the previous month’s closing balance, or att_entry()the account value entering the frame,av_pp_init(). It is written here inline, asav_pp_at(t, BEF_WD)writes it too, so that the chain of calls from month t back tot_entry()is one cell a month, whereMYGA_US_S’s ran throughav_pp_atat two timings, three cells a month. No charges are deducted from the account value: this chassis carries no front-end load, no annual fee and no rider charges [S5][S10][S13][S16]. 0.0 outside cover.
- av_pp_at(t, timing)[source]#
Account value per contract at month t, read at the point given by
timing.BEF_WDisAV(t-1), the opening balance —av_pp_init()att_entry()andav_pp(t - 1)after, plus the premium credited in the issue month — written asav_pp()writes its own opening, so thatav_pp()need not call this cell;BEF_INVisAV'(t) = AV(t-1) - W(t);EOMisAV(t), the closing balance. 0.0 outside cover, at every timing.
- interest_credited_pp(t)[source]#
Cumulative interest credited to one contract from issue to the end of month t.
Used by the
min_sc_interestMVA cap, which limits the adjustment to the lesser of the surrender charge and the interest credited to date [S8][S9], and by the interest-only free-withdrawal allowance. The interest credited before the valuation date opens it att_entry(),interest_credited_pp_init(); nothing has been credited before issue. 0.0 outside cover.
- prem_accum_gmir_pp(t)[source]#
Premium less prior withdrawals accumulated at the GMIR, at the end of month t.
The reference level for the
gmir_floorMVA cap, under whichAV + Mmay not fall below it [S13]; the surrender charge may still breach that level. The premium itself enters in the issue month, as inMYGA_US_S, and a point in force opens fromprem_accum_gmir_pp_init()att_entry(). 0.0 outside cover.
- free_wd_base(y)[source]#
FWB(y): the free-withdrawal base fixed at the start of contract year y.
Purchase payments in year 1, the account value at the most recent anniversary thereafter [S10] — the opening balance of policy month
12 (y - 1), the first month of yeary:av_pp_at(t, BEF_WD)at the valuation monthtthat policy month falls in. Making the base a fixed known amount at each anniversary is what letsE(t) = AV(t) - FW(t)be evaluated without a fixed point. It is asked only for a year that opens on the books: the year under way at the valuation date takes its allowance fromfree_wd_allow_init(), and needs no base.
- free_wd_allow(y)[source]#
The free-withdrawal allowance for contract year y, non-cumulative [S4][S16].
pct_av:free_wd_rate x FWB(y)[S10].interest_only: the interest credited over the prior contract year [S5][S6] — cumulative interest at the end of the last month of yeary - 1less that at the end of the last month of yeary - 2— hence zero in year 1.greatest_of[S13] is not implemented and raises.Asked for the contract year under way at the valuation date, a year
y > 1that opened at or before it, the allowance is the opening state’s,free_wd_allow_init(), under either rule. For the year after it underinterest_only, the interest at the anniversary that opened the year under way is the opening state’s too,interest_credited_pp_prev_anniv_init(). Every later year is computed from the frame, its anniversaries’ policy months turned into valuation months; no formula asks for a year that closed before the valuation date.
- free_wd_avail(t)[source]#
FW(t): the unused free-withdrawal allowance at BOM of month t, before W(t).
Reset to the whole allowance in the first month of each contract year, where
duration_mth(t)is a multiple of 12, the issue month included; carried forward within the year; never carried across an anniversary [S4][S16]. The carry is the previous month’s allowance less its free withdrawal —free_wd_remain()of montht - 1, written out here so that the chain of calls back to the year’s reset is one cell a month — and att_entry()off an anniversary it isfree_wd_remain_init(), the remainder carried into the valuation date. 0.0 outside cover.
- wd_free_pp(t)[source]#
The portion of W(t) covered by the free allowance, hence free of charge and MVA.
- free_wd_remain(t)[source]#
The unused free-withdrawal allowance after month t’s withdrawal.
This, not
free_wd_avail(), is the allowance a full surrender at the end of month t may still shelter.
- wd_excess_pp(t)[source]#
E(t) for a partial withdrawal:
max(0, W(t) - FW(t))[S8][S9][S10].The whole of W(t) when
free_wd_mva_exemptis False [S3][S4].
- surr_excess_pp(t)[source]#
E(t) for a full surrender at the end of month t:
AV(t) - FW(t)[S8][S11].The whole of AV(t) when
free_wd_mva_exemptis False [S3][S4].
- surr_charge_id(t)[source]#
The surrender charge schedule in force:
INITIAL,RENEWALorNONE.Under
rollovera fresh renewal schedule attaches at each guarantee-period boundary [S1][S2][S11]; underannual_redeclareno charge applies after the initial term [S13]. Getting this clock wrong relocates the shock lapse by years.MYGA_US_Sreturns the schedule’s key in surr_charge_table.csv,initialorrenewal, ornone; here each is a code (the Space docstring’s Codes), andINITIALandRENEWALare the rows ofdata.surr_charge_array()that hold the two schedules.Datarefuses a table that lacksinitialorrenewal.
- surr_charge_year(t)[source]#
sc_clock: the contract year within the schedule in force, 1..n.
policy_year(t) - n (gp_index(t) - 1): 1 for policy months0 .. 11and again for the first twelve months of each renewal period. Resets to 1 at each renewal underrollover[S1][S2][S11]. The two registered contracts instead run the clock from the original purchase payment date so it never restarts [S3][S4]; that variant is not carried on this chassis.
- surr_charge_age_cap(t)[source]#
The attained-age cap on the surrender charge in month t [S1] [S2].
surr_charge_age_cap_at()at the attained age,age(t): 4% at 94 down to 0% at 98-100, and 1.0, no cap, below the sourced age band. 0.0 outside cover, where no age is the contract’s.
- surr_charge_age_cap_at(a)[source]#
The attained-age cap on the surrender charge at attained age
a, from its table.4% at 94 down to 0% at 98-100 [S1] [S2]; 1.0, no cap, below the sourced age band, and the last row’s value above it. The one cell that reads surr_charge_age_cap.csv, keyed by age:
surr_charge_age_cap()calls it atage(t), inside cover only. The band’s first and last ages aredata.surr_charge_age_cap_first()anddata.surr_charge_age_cap_last(), taken from the agesDatahas checked before a cap is read, and the cap is one element ofdata.surr_charge_age_cap_array(), the same checked table by attained age from 0, read only from the first age on, where it holds no padding.Datarefuses a negative age, so the first is 0 or more.
- surr_charge_rate(t)[source]#
sc(y): the surrender charge rate in force at month t.
9/8/7/6/5 over the initial term [S10] and 5/4/3/2/1 over a renewal term [S2], capped by the attained-age scale [S1][S2], zero once a schedule runs out, and zero in the 30-day guarantee-period-end window [S1][S2]. The schedules’ one reader:
Dataholds the two the projection reads indata.surr_charge_array(), by schedule code and contract year, from the table checked, where each runs from year 1 without a gap, and each schedule’s last year indata.surr_charge_last_years(). So the rate is one element, at the codesurr_charge_id()returns and the year of the schedule’s clock, and a year past the schedule’s last has no charge, whereMYGA_US_S’s lookup missed and returned 0.0. Neither theNONErow, the year-0 column nor a year past a schedule’s last is read, which hold padding. 0.0 outside cover, before any schedule is read.
- mva_term(t)[source]#
T(t): the MVA duration in years at the end of month t [S8].
The notes write it as (days to the end of the current contract year / 365) + whole years remaining in the MVA period. On a monthly grid those two terms collapse algebraically to
(12 n k - (d + 1)) / 12withd = duration_mth(t)— the time from the end of monthtto the end of the current MVA period,k = gp_index(t)— and the same quantity serves as the geometric branch’stau, which the notes define as days to maturity / 365.25. The two divisors differ in the sources; on exact twelfths they cannot. 0.0 outside cover, as once the MVA period has run out. The whole years remaining aremva_term_years(), an int, asMYGA_US_S’s localwhole_years_leftis, so the sum isMYGA_US_S’s.
- mva_term_years(t)[source]#
The whole years of T(t): the MVA period’s years left after the current one, an int.
n k - ywithk = gp_index(t)andy = policy_year(t), 0 or more in cover, wheremva_term()adds the months to the end of the current contract year, at most 11/12. Soint(mva_term(t))is this wherevermva_duration_factor()reads it, which reads it here instead: anint()of a float compiles to Python arithmetic, and this to C. 0 outside cover and once the MVA period has run out, wheremva_term()is 0.0.
- mva_in_force(t)[source]#
True when an MVA applies at month t.
mu(t) = 0unconditionally once the MVA period has expired [S8][S13][S16] and in the 30-day guarantee-period-end window [S2]. It is also zero on a death benefit [S2][S4][S8][S13][S16], on annuitization [S16], and on RMD or waiver withdrawals [S2][S5][S13]; the first two are handled where those benefits are valued and the third is not implemented. False outside cover.
- mva_ref_yield_locked(t)[source]#
i0: the reference yield locked at the start of the current guarantee period.
The model point’s issue value for the initial term; re-locked at the prevailing reference yield at each renewal under
rollover[S2][S11], read at the valuation month the period starts in,gp_start_month()turned intot. A period that started beforet_entry()was locked at a yield of the past, the opening state’smva_ref_yield_locked_init(). 0.0 outside cover.
- mva_ref_term_years(tau)[source]#
The whole-year maturity at which the distribution yield is read [S4].
Partial years round up, capped at the guarantee period: one registered contract reads a 3-year yield for 985/365.25 = 2.69 years remaining while the exponent keeps the exact day count. With a single scalar reference yield per scenario this selection determines nothing; it is carried so a curve-valued extension has the rule in place.
An engine cell,
MYGA_US_S’s formula unchanged,mathincluded, asmgsv_rate_statutory()is: no projection cell calls it. Compiled, it returns a Clong long, so a term below-2**63, outside any term, overflows there, where modelx returns Python’s int.
- mva_duration_factor(t)[source]#
F_s: the declared-differential adjustment factor by years remaining [S14].
A contractual table of modified durations, read on the
Ic < 6%orIc >= 6%column and linearly interpolated between whole years, flat beyond the last row,data.mva_factor_last_year(), taken from the yearsDatahas checked. The table’s one reader:data.mva_factor_array()holds it by whole year remaining, 0 to the last,factor_loin column 0 andfactor_hiin column 1, and each factor is one element, at the whole yearsmva_term_years(), 0 or more in cover, and the year after, read only below the last. The years are read here, keyed byt, rather than through a cell keyed by the year: their bound is the table’s last year and the guarantee period, data no contract bound holds, from which no cache could be sized. 0.0 outside cover, before the table is read.
- mva_rate(t)[source]#
mu(t): the market value adjustment rate at month t, signed and dimensionless.
linear_duration[std]:(i0 - it) x T(t)[S8][S9] — the first-order approximation of the geometric form, always in the contract holder’s disfavour when rates rise.geometric:Phi(t) - 1[S3][S4], where the factorPhi = ((1 + i0) / (1 + it + s_adm)) ** T(t), withs_admthemva_admin_spread, 25 bp in one registered contract [S4], covering the cost of liquidating fixed-income investments and structurally biasing the adjustment against the owner; the other registered variant sets it to zero [S3].MYGA_US_Scomputes the factor in a cell of three float parameters,mva_factor_geometric, which here is written inline, the same expression in the same order, since a cell keyed by floats compiles to a Python dict.declared_differential:(Ic - In) x F_son the insurer’s own new-money rate [S14], withIntaken as the market rate [std].The geometric factor’s numerator and divisor are bound to locals in
MYGA_US_S’s order, and a divisor of zero, a reference yield of-1 - s_adm, raisesZeroDivisionErrorhere with Python’s message,float division by zero, asMYGA_US_Sraises it, which compiled division would word otherwise.
- mva_pp(t)[source]#
M(t): the capped MVA on a full surrender at the end of month t.
The MVA rate on the surrender’s base,
surr_excess_pp(), capped by one of five rules, all first-class parameters because the cap is the largest single cross-carrier divergence in the source set:sym_sc[std]clamp(M_raw, -C, +C)[S2].min_sc_interestclamp(M_raw, -K, +K)withK = min(C, interest credited to date)[S8][S9].asym_sc_snflM <= +Cwith no downside cap; onlySB >= MGSVbinds below [S12].gmir_floorAV + M >=premium less prior withdrawals accumulated at the GMIR [S13]. The floor is stated for a full surrender; applying it to a partial withdrawal base is an extension of the source.noneUncapped and fully two-sided [S3][S4].
MYGA_US_Scaps an MVA on any currency base in one cell,mva_pp_on(t, base), which this andwd_mva_pp()call. A cell keyed by a float compiles to a Python dict, so here each writes the cap inline on its own base, the same expressions in the same order. A rule none of the five raises, as there.
- wd_mva_pp(t)[source]#
The capped MVA on month t’s partial withdrawal.
mva_pp()’s cap, on the withdrawal’s base,wd_excess_pp(), written inline as there.
- surr_value_pp(t)[source]#
SV(t): the gross surrender value,
AV(t) + M(t) - C(t), before the floor.The composition order is account value, then MVA, then surrender charge, then the nonforfeiture floor, and it is not interchangeable: both M and C are computed on E(t) before either is deducted [S8]. Charging first and adjusting the net figure understates the adjustment by
sc x |M|; flooring before the MVA silently removes the downside protection.
- surr_benefit_pp(t)[source]#
SB(t): the surrender benefit actually paid,
max(SV(t), MGSV(t))[S8][S9][S12].A binding floor is not a separate cash flow: it raises SB(t), and
MGSV(t) - SV(t)is a reconciliation quantity only.
- mgsv_pp_init()[source]#
MGSV(-1): the Model #805 floor per contract entering month 0.
The
mgsv_pp_initcolumn: for a point in force, the floor at the close of policy monthduration_mth_init() - 1, before any month-0 event, whatMYGA_US_Scarries into that month as themgsv_ppof the month before, and the opening value ofmgsv_pp()att_entry(). It may be negative: every withdrawal is deducted from the floor and nothing floors it at zero, in either model, so heavy withdrawals take it below. Zero for a point not yet in force: its floor opens with 87.5% of gross consideration in the issue month,prem_to_mgsv_pp().MYGA_US_S’s cell of the name computes that issue value; here the rule moved to the issue month, where it stays a rule.
- prem_to_mgsv_pp(t)[source]#
The consideration the Model #805 floor opens with, per contract, in the issue month.
net_consideration_ratio x P, 87.5% of gross consideration [R1 4.A(2)][S11], at BOM of the month withduration_mth(t) = 0, and 0 in every other month. It is the notes’mgsv_initial, whichMYGA_US_Scomputes asmgsv_pp_init(): computed by the statutory rule rather than read, because shipping it as data would let a model point silently violate the statute.
- mgsv_charge_pp(t)[source]#
c(t): the monthly slice of the annual contract charge deducted from the floor.
0.0 outside cover, where there is no contract to charge.
- mgsv_wd_deduct_pp(t)[source]#
d(t): the withdrawal deducted from the Model #805 floor in month t.
W(t) under the
grossconvention [S11]; the cash actually paid,W(t) + M(t) - C(t), undernet_of_charges[S9].
- mgsv_pp(t)[source]#
MGSV(t): the Model #805 minimum guaranteed surrender value at end of month t.
MGSV(t) = [MGSV(t-1) - d(t) - c(t)] x (1 + i_nf)^(1/12)[R1 4.A][S11], with the consideration the floor opens with,prem_to_mgsv_pp()= 0.875 x P, added to the opening value in the issue month. The opening valueMGSV(t-1)is the previous month’s closing value, or att_entry()the floor entering the frame,mgsv_pp_init(). Premium tax actually paid and indebtedness are further permitted deductions, accumulated at the same rate, and are zero here. 0.0 outside cover.
- taxable_wd_pp(t)[source]#
The income-first taxable portion of month t’s withdrawal [R6 72(e)(3)(A)].
Taxable to the extent the account value gross of surrender charge exceeds the basis at the start of the month, which at
t_entry()istax_basis_pp_init(). A reported quantity: it generates no insurer cash flow. 0.0 outside cover.
- tax_basis_pp(t)[source]#
basis(t): the IRC 72 investment in the contract at the end of month t [R6].
Reduced only by the non-taxable remainder of a withdrawal; the opening basis of month
t_entry()istax_basis_pp_init(). Reported, not a cash flow. 0.0 outside cover.
- mort_rate(t)[source]#
The annual mortality rate at the attained age and sex, from mort_table.csv.
The shipped table is an illustrative Makeham curve [std], not a published basis. The prescribed basis is the 2012 IAM Basic table with Projection Scale G2 and the VM-22 Table 6.7 factors [R2 6.B.8][R9], which may not be redistributed here; swap it in by repointing
Data.mort_table_filebefore the model computes anything. Mortality is second-order on this product: death pays the full account value with no charge and no MVA. 0.0 outside cover, before the table is read.No factor multiplies the table’s rate, and
Datarefuses a rate outside 0 to 1, so none is above 1, and none is capped: the shipped rates in cover are 0.263 at most, at attained age 99. The rate ismort_rate_at(), the table’s one reader, at the attained age,age(t).Datarefuses a point whose sex the table lacks, or whose attained age in its first month on the books it gives no rate at, andproj_len()one whose sex it rates only below the attained age of the last covered month, whereMYGA_US_Sraises itsKeyErroronce the projection gets there; on the shipped table, which runs to 120, no contract reaches one.
- mort_rate_at(a)[source]#
The annual mortality rate at attained age
afor the point’s sex.The one cell that reads mort_table.csv, keyed by age, as
surr_charge_age_cap_at()is:mort_rate()calls it atage(t), inside cover only.Dataholds the table checked indata.mort_table_array(), by sex, numbered asmort_schedule()numbers it, and attained age from 0, and each sex’s first and last age indata.mort_age_firsts()anddata.mort_age_lasts(). An age outside the sex’s is refused, naming the point and the age, whereMYGA_US_S’s lookup raised aKeyError; inside, the rate is one element, never padding.Datarefuses a negative age, so the first is 0 or more.
- gmir_factor()[source]#
G: the VM-22 GMIR factor stepping the base lapse rate [R2 6.B.5].
1.25 at a GMIR of 1.0% or less, 1.00 up to 2.5%, 0.70 above. The representative 0.25% GMIR [S11] therefore takes the highest multiplier, which is the conservative end of the prescribed scale.
- lapse_rate_base(t)[source]#
Base(y): the prescribed base lapse rate for the contract year containing month t.
VM-22 Table 6.5 mapped onto the five-year architecture as a [std] extension [R2][REG-R36].
rollover: 1% inside each guarantee period and 75% in the contract year following each expiry, repeating with period n.annual_redeclare: 1% to expiry, 75%, then 10%, 7.5% and 3% thereafter. The architecture switch, not the level, is the first-order modeling decision — Camp A creates a repeating shock, Camp B a single one. 0.0 outside cover, where no contract year is the contract’s.
- lapse_dyn_exponent(t)[source]#
X: the dynamic-lapse exponent [R2].
2.0 during the initial surrender charge period, 2.5 at the shock and after. 0.0 outside cover.
- lapse_dyn_market(t)[source]#
Market(t): the credited-minus-competitor response of the VM-22 dynamic lapse form.
-1.25 (CR - MR)^Xwhen the contract is competitive, zero inside the 50 bp buffer,+1.25 (MR - BF - CR)^Xwhen it is not [R2 6.B.5]. The buffer and the power make the sensitivity strongly convex aroundCR = MR. 0.0 outside cover.
- lapse_dyn_rate(t)[source]#
Rate(t): the dynamic term gated by the surrender-charge and negative-MVA haircut.
Market(t) x max(0, 1 - 5 (1 - CSV/AV))withCSV/AV = SB(t)/AV(t)[R2 6.B.5], so the dynamic response switches off entirely once the combined haircut reaches 20%. The ITM factor is 1 for an Accumulation contract with no guaranteed living or death benefit, which the guideline states explicitly. 0.0 outside cover, where the surrender benefit and the account value are both 0.0 and their ratio would be 0/0.In cover, an account value of zero, which a scheduled withdrawal of the whole account value reaches, raises
ZeroDivisionError, asMYGA_US_Sdoes: the divisor is tested and the error raised here, with Python’s message,float division by zero, which compiled division would word otherwise. The two operands are read inMYGA_US_S’s order, the surrender benefit first.
- mva_lapse_factor_at(t)[source]#
Phi_MVA(t): the factor multiplying the dynamic term while an MVA is in force.
The VM-22 prescribed values are 0 in force and 1 expired [R2], i.e. the regulator’s view is that an in-force MVA completely neutralizes disintermediation. The model exposes the in-force value as
mva_lapse_factor, defaulting to the best-estimate 0.35 [std] rather than the prescribed 0; set it to 0 for the statutory run. It is a judgement, not a calibration — sensitivity-test it.
- lapse_rate(t)[source]#
w_annual(t):
clamp(Base(y) G + Rate(t) Phi_MVA(t), 0.005, 0.90)[R2 6.B.5].The annual total surrender rate, paired with
lapse_rate_mth()exactly asmort_rate()is paired withmort_rate_mth().On the base deterministic run
MR = CRandrenewal_spread = 0, soMarket(t) = Rate(t) = 0and this isBase(y) x 1.25: contract years 1 to 5 at 1.25% and the shock year at 90%, the 93.75% product capped. 0.0 outside cover, where the clamp would otherwise give its 0.5% floor.
- lapse_rate_mth(t)[source]#
w(t): the monthly total surrender rate,
1 - (1 - w_annual)^(1/12).This is the rate the monthly decrement actually applies;
lapse_rate()is the annual rate it is derived from.
- annuitization_rate(t)[source]#
a(t): the monthly annuitization election rate.
1.0% of in-force in each 30-day guarantee-period-end window after contract year 1 and zero elsewhere [std]. No public annuitization take-up study for deferred annuities was located; VM-22 prescribes 0% at all projection intervals for the standard projection [R2 6.B.6], which is a statutory simplification rather than an experience estimate. Set
annuitization_rate_window = 0for the statutory alternative.
- pols_if(t)[source]#
l(t-1): the number in force at the start of month t, the weight of row t.
pols_if_at(t, BEF_DECR): the count carried in from month t - 1 plus month t’s new business, before month t’s decrements — the population that takes the month’s withdrawal, carries its expenses and is exposed to its decrements, so it is the weight on every cash flow of the sameresult_cf()row. On a point issued att = 0it is exactlyMYGA_US_S’spols_if. A point in force at the valuation date opens withpols_if_init(), and one issued at or after it with its issued count in the issue month. Zero outside cover: before issue, and fromt = proj_len()on, because the survivors of the last covered month are annuitized out throughpols_maturity().It is
basiclife.BasicTerm_SE’sBEF_DECRcount, not itspols_if, which is the count before maturity. The notes’ end-of-monthl(t) = l(t-1)(1 - a(t))(1 - q(t))(1 - w(t))ispols_if_at(t, AFT_DECR), which equalspols_if_at(t + 1, BEF_NB)in every month but the last covered one.
- pols_new_biz(t)[source]#
Number of contracts issued in month t:
policy_count()in the issue month.The issue month is the one with
duration_mth(t) == 0:t = 0for a point issued at the valuation date,t = kfor one issuedkmonths later. A point already in force at the valuation date has none.
- pols_if_at(t, timing)[source]#
In-force at month t read at the point given by
timing.The timings in processing order:
BEF_NBthe count carried in from month t - 1, before month t’s new business: the survivors of month t - 1’s annuitizations, deaths and surrenders, out of month t - 1’s
BEF_DECRcount. Att_entry(), the first month on the books, it ispols_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. Zero outside cover, so the survivors of the last covered month leave aspols_maturity().BEF_DECRl(t-1):BEF_NBpluspols_new_biz(), before any decrement; the same number aspols_if(), and the weight on that month’s cash flows.BEF_MORTafter annuitization elections,
l(t-1)(1 - a(t)).BEF_LAPSEafter deaths,
l(t-1)(1 - a(t))(1 - q(t)).AFT_DECRafter surrenders,
l(t)— the notes’ end-of-month in-force, which in the last covered month is whatpols_maturity()annuitizes out.
The order is the notes’
l(t) = l(t-1)(1 - a)(1 - q)(1 - w)[std order].BEF_NBandBEF_DECRarebasiclife.BasicTerm_SE’s names, and any timing but these five raises.BEF_NBforms the count left at the end of month t - 1 itself — month t - 1’sBEF_NBplus itspols_new_biz(), after its three decrements, the productsAFT_DECRtakes in the order it takes them — rather than calling for it. So the chain of calls from month t back tot_entry()is one cell a month, whereMYGA_US_S’s ran through two. Every count is zero outside cover, before any rate is read.
- pols_annuitization(t)[source]#
Annuitization elections in month t, taken at BOM before crediting.
Zero outside cover.
- pols_death(t)[source]#
Deaths in month t, on the in-force net of annuitization elections.
Zero outside cover.
- pols_lapse(t)[source]#
Full surrenders in month t, on the survivors of annuitization and mortality.
Zero outside cover.
- pols_maturity(t)[source]#
Deemed-maturity annuitizations, non-zero only in the last covered month.
That month is
duration_mth(t) = maturity_mth() - 1, the frame’s last row,t = proj_len() - 1. Not a decrement — the projection horizon runs out — but needed for the in-force roll-forward to close; see the Space docstring.
- annuitization_pp(t)[source]#
The amount transferred to the payout model on an annuitization election.
The full account value
AV'(t)in the 30-day window; outside it,AV'(t)less the surrender charge computed onAV'(t), with no MVA [S1][S2][S5][S16][std].The notes name
SV(t)for the non-window case, andSV(t) = AV(t) + M(t) - C(t)is composed on the post-crediting account value — but the same notes make annuitization an elective BOM transaction and setmu(t) = 0on it. The two cannot both hold on a monthly grid, and the model resolves it at BOM: annuitizers leave before the month’s interest is credited, which is exactly whatclaim_from_av_pp()releases for them (AV'(t), notAV(t)). This cell is therefore the BOM analogue ofSV(t)— the same composition on the account value the annuitant actually takes with them. ReadingSV(t)literally would pay out one month of interest the block never credited to those contracts, and the difference(AV(t) - AV'(t)) * (1 - sc(y))would surface as a spuriousclaims_over_av(). The choice is inert on every shipped model point, wherea(t)is zero outside the window; a test pins it open.No nonforfeiture floor is applied in either branch:
SV(t)is the pre-floor value. Payout factors are out of scope: no retrieved product document contains an annuity rate table, so the accumulation model emits the transfer and hands the amount on.
- claim_pp(t, kind)[source]#
The benefit paid per contract in month t by
kind.DEATHis the full account value with no charge and no MVA [S1][S2][S13], floored at the cash surrender benefit and hence at MGSV(t) [R1 6]; on the base run the floor is inert because 4.45% exceeds 2.80%, but at a renewal rate down to the GMIR it overtakes the account value, so it is tested at every duration [std].LAPSEis SB(t).ANNUITIZATIONisannuitization_pp().MATURITYis the account value floored at MGSV at the projection horizon.
- claim_from_av_pp(t, kind)[source]#
The account value released per contract by a claim of
kind.Equal to
claim_pp()except where the Model #805 floor binds; the difference isclaims_over_av(). Annuitizers leave at BOM and so releaseAV'(t), before the month’s interest.
Premium income: the single purchase payment, on the contracts issued in month t.
premium_pp() x pols_new_biz(t), a beginning-of-month flow of the issue month, the notes’ “att = 0”. A point in force at the valuation date paid its premium before it, and has none.
- withdrawals(t)[source]#
Withdrawal payments in month t:
(W(t) + M(t) - C(t))weighted byl(t-1).The ledger separates the free part (
wd_free_pp, never charged or adjusted) from the excess (wd_excess_pp); this line is the total cash paid. The weight ispols_if(), the start-of-month count printed on this same row ofresult_cf(), because the withdrawal is taken at BOM before any decrement. Zero outside cover.
- claims(t, kind)[source]#
Benefit outgo in month t, for one
kindor, withALL, all four.ALLisMYGA_US_S’skind=None, its total, a code here (the Space docstring’s Codes), since a parameter that is sometimesNonecompiles to a Python object. The total isMYGA_US_S’s expression, the four kinds added left to right, so it isMYGA_US_S’s bit for bit, a negative zero included.ALLis the one code this takes thatclaim_pp()andpols_decr()refuse.
- claims_over_av(t, kind)[source]#
Benefit paid less the account value released,
claims - claims_from_av.Signed, and normally negative on this chassis: a surrender pays out less than the account value it releases, by the surrender charge and any negative MVA. It turns positive exactly when the Model #805 floor binds and SB(t) exceeds AV(t). Either way it is a reconciliation quantity, not a cash flow of its own — a binding floor raises SB(t), it does not add a separate top-up line, and the charge and the MVA are internal accounting entries rather than ledger lines. With
ALL, all four, asclaims()totals them.
- commissions(t)[source]#
Acquisition commission: 2.00% of premium paid at issue, in the issue month [std].
No retrieved document discloses MYGA commission; this is a pure modeling assumption.
Premium tax on the purchase payment, 0% [std] [S3][S16].
- inflation_factor(t)[source]#
The expense inflation factor in month t,
(1 + inflation_rate) ** (t // 12).On the valuation clock:
tcounts months from the valuation date, so the maintenance charge it inflates is in valuation-date dollars, whatever the contract’s age, and every point of a block inflates alike.MYGA_US_S’s annual step is kept,1.025^kfromt = 12 kto12 k + 11, but it falls every twelve months from the valuation date rather than on the contract’s anniversaries. On a point issued att = 0the two are the same; on the anchor cell in force 12 months this model’s charge isMYGA_US_S’s divided by 1.025 in every month. Defined in every month, before issue too: it is an input, not a state of the contract.
- expenses(t)[source]#
Insurer expenses: acquisition on new business and inflating maintenance [std].
(50 / 12) x 1.025^(t // 12)per contract per month on the valuation clock, in-force weighted, plus the acquisition expenseexpense_acqper contract issued, in the issue month, onpols_new_biz()and not inflated, as inbasiclife.BasicTerm_SE. A point in force at the valuation date never sees it, because it was issued before;MYGA_US_Scharges it att = 0on the contracts in force there, which on a point issued att = 0is the same charge. VM-22 prescribes $35 x 1.025^(offset) per contract for business the company does not administer [R2 6.B.3]; the $50 figure is a [std] uplift of that anchor to a self-administered block.expense_acqis 0 because this chassis’s only acquisition cost is the commission. Zero outside cover.
- net_cf(t)[source]#
Net cash flow in month t.
Interest credited, the surrender charge, the MVA and the movement of the Model #805 floor are internal accounting entries, not ledger lines: they drive AV, MGSV and the benefit amount but are never cash flows of their own. Only amounts paid to or received from the contract holder, and the insurer’s own expenses, appear here.
- av_at(t, timing)[source]#
The in-force weighted account value at month t; see
av_pp_at()fortiming.Each timing carries the in-force appropriate to that point in the month:
l(t-1)before the withdrawal,l(t-1)(1 - a(t))once annuitizers have left, and at the end of the month the count that survives every exit —pols_if_at(t + 1, BEF_NB), the count carried into the next month before its new business, which isl(t)except in the last covered month, where the deemed maturity empties the block. Usingpols_if_at(t, AFT_DECR)there would leave the matured account value standing in the block and released as a claim, andcheck_av_roll_fwd()would not close. In the issue month theBEF_WDvalue is the premium just deposited, on the contracts just issued.
- wd_from_av(t)[source]#
The account value released by month t’s withdrawals, gross of charge and MVA.
- av_change(t)[source]#
The change in the block’s account value over month t.
Closing balance less the previous month’s closing balance. At
t_entry()the previous balance is the block’s account value entering the frame,av_pp_init() * pols_if_init(), which is nothing for a point not yet in force: its block holds nothing before the purchase payment, so in the issue month the change is the whole closing balance andprem_to_av()is the deposit that explains it.
- check_av_roll_fwd_resid(t)[source]#
Account value roll-forward residual in month t; zero to floating point.
AV(t) - AV(t-1) = premium in - withdrawals out + interest credited - the account value released by each of the four claim kinds. Note that the cash paid on a surrender may exceed the account value released when the Model #805 floor binds; that excess isclaims_over_av()and is not part of this identity. In the issue month the premium deposit is thepremium interm; a point in force opens from its block’s account value entering month 0 (av_change()).The signed residual, for a debugging session that needs to know where and by how much
check_av_roll_fwd()failed.
- check_av_roll_fwd()[source]#
True when the account value roll-forward closes in every projected month.
Takes no argument and returns a bool, following
CashValue_SE.check_av_roll_fwdand the library convention, so one test can call the same check across every model.check_av_roll_fwd_resid()carries the per-month signed residual, and this isabs(resid) <= check_tol_av x max(policy_count(), 1)overt = 0 .. proj_len() - 1: the tolerance scales with the count, since the residual is rounding on that many contracts. On a point counting one contract it isMYGA_US_S’s check.
- check_pols_roll_fwd_resid(t)[source]#
In-force roll-forward residual in month t; zero to floating point.
pols_if(t) - pols_if_at(t + 1, BEF_NB) = annuitizations + deaths + surrenders + deemed maturities: the start-of-month count opens the row, the four exits are taken during it, and the next month opens on what is left, before its own new business, which is no part of month t’s movement. In the notes’ own indexing that isl(t-1) - l(t), sincepols_if()is the start-of-month count.The signed residual;
check_pols_roll_fwd()is the bool over allt.
- check_pols_roll_fwd()[source]#
True when the in-force roll-forward closes in every projected month.
No argument, returns a bool over
t = 0 .. proj_len() - 1, matchingcheck_av_roll_fwd()and the library convention. The tolerance ischeck_tol_pols x max(policy_count(), 1), scaling with the count as the residual does.
- result_cf()[source]#
Result table of cashflows, one row per month
t = 0 .. proj_len() - 1.Row 0 is the valuation 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
MYGA_US_S’s. The purchase payment, the acquisition commission and the premium tax are beginning-of-month flows of the issue month, the notes’ “att = 0”, and sit on the same row as that month’s interest, decrements and maintenance expense.The
pols_ifcolumn is the start-of-month count, which is the weight applied to every cash flow on that same row, so the printed in-force reconciles with the printed flows:withdrawals(t) / wd_payment_pp(t)andexpenses(t) / ((expense_maint / 12) * inflation_factor(t))both return it, the second outside the issue month.
- result_pols()[source]#
Result table of in-force movements, one row per month
t = 0 .. proj_len() - 1.The counts
result_cf()weights its rows by, and how they move, asbasiclife.BasicTerm_SE’sresult_polssets them out:pols_if, the count of month t;pols_new_biz, the part of it issued in month t; then month t’s annuitizations, deaths and surrenders in processing order, and the deemed maturities of the last covered month; thenpols_if_aft_decr, the notes’ end-of-monthl(t), as inMYGA_US_S. Row by row,pols_ifatt + 1ispols_ifless the four outflows of month t, plus the new business of montht + 1, andpols_if_aft_decris that count before the new business in every month but the last covered one, where the deemed maturity empties the block. Zeros before issue.
- result_av()[source]#
Result table of per-contract account value and surrender values, by month t.
One row per month
t = 0 .. proj_len() - 1, zeros before a point’s issue. The first five columns are the worked example’s table — the opening balanceAV(t-1),W(t),AV'(t), the closing balanceAV(t)andMGSV(t)— and the rest are its surrender trace, available at every duration. The trace’sfree_wd_availcolumn,MYGA_US_S’s name, holdsfree_wd_remain(), the allowance left after the month’s withdrawal, which a surrender at the end of the month may still shelter, notfree_wd_avail(), the allowance before it.