Concepts – Household Optimizer

This document explains the core concepts behind the NTS household optimizer that powers the Allocator API.

The goal is to give advisors and advanced users enough intuition to:

• Choose sensible parameters (n_sims, local_iters, grid_step, etc.).
• Understand what the engine is trying to optimize.
• Interpret the PPTX reports generated by the worker.

Note: All public examples are designed to use the Allocator API, not direct engine imports.
You interact with the optimizer by submitting jobs to /allocator/jobs.

---

1. Problem Framing

The optimizer models a household with multiple asset locations, typically including:

• A CRT (charitable remainder trust) sleeve.
• A taxable sleeve.
• Potentially other sleeves (IRAs, Roth, etc.) in more advanced configurations.

Each job describes:

• A starting balance in CRT and taxable sleeves.
• A time horizon in years.
• A payout rate (e.g., unitrust payout from the CRT).
• A simulation and optimization configuration.

The engine then:

1. Simulates many possible future return paths across sleeves.
2. Evaluates household outcomes under various policy / allocation choices.
3. Searches over those choices to find policies that best satisfy the objective function (risk/parity, min variance, custom).

The result is a PPTX report that summarizes distributions of outcomes, trade‑offs, and policy recommendations.

---

2. Key Parameters

The most important knobs exposed in AllocJobSpec are:

2.1 n_sims

Number of simulation paths.

• Higher n_sims ⇒ smoother distributions and more stable estimates.
• Lower n_sims ⇒ faster runs, but noisier outcomes.

Typical ranges:

• 1,000 – 3,000 for demos / quick iteration.
• 5,000 – 10,000+ for more serious production work (depending on hardware).

2.2 local_iters

Number of local search iterations per grid point.

The optimizer usually has a coarse grid over top‑level policy parameters (e.g., CRT vs taxable allocation, payout tweaks).
At each grid point, it can run a local improvement loop:

• Propose small adjustments.
• Accept moves that improve the objective.
• Repeat up to local_iters times.

Higher local_iters:

• More thorough local search.
• More compute per grid point.

Lower local_iters:

• Faster runs.
• More dependence on the initial grid resolution (grid_step).

2.3 grid_step

Step size of the coarse grid over policy parameters.

Think of this as the resolution of the outer search:

• Larger grid_step (e.g., 0.10) ⇒ fewer grid points, coarser search.
• Smaller grid_step (e.g., 0.05 or 0.025) ⇒ more grid points, finer search.

A common pattern:

• Start with grid_step = 0.10 and modest local_iters to get a feel for the landscape.
• Tighten to 0.05 if the results suggest a narrow band of “good” policies worth exploring more.

2.4 objective

High‑level goal of the optimization.

Supported values (initially):

• "risk_parity" – Balance risk contributions across sleeves / policies.
• "min_var" – Focus on minimizing variance of key outcome metrics.
• "custom" – Use a custom objective that blends multiple metrics (e.g., expected wealth, downside risk, CRT remainder values).

In all cases, the details of the objective function live inside allocator_engine.
The API contract remains stable even as you refine the internals.

---

3. Default Economic Assumptions

Each job may carry additional parameters, either from defaults or explicit overrides:

• start_crt – Initial CRT value (e.g., 8.5M).
• start_tax – Initial taxable value (e.g., 7.5M).
• years – Horizon in years (e.g., 30).
• payout_rate – CRT payout rate (e.g., 8.5% as 0.085).

These values influence:

• Cash‑flow patterns across sleeves.
• Tax drag and reinvestment.
• Remainder values for the charitable entity vs. the family.

The PPTX report surfaces these assumptions clearly so an advisor can validate them with the client.

---

4. Job Flow

Conceptually, a single job proceeds through:

1. Setup
2. Read job spec and household inputs.

3. Configure simulation engine with economic assumptions and policy knobs.

4. Simulation

5. Generate n_sims independent paths of returns and relevant risk factors.

6. Track sleeve balances, payouts, and taxes over years.

7. Optimization

8. For each grid point (driven by grid_step), evaluate the objective across all sims.
9. Run local search up to local_iters times to refine promising policies.

10. Track the best‑performing policies and their metrics.

11. Reporting

12. Populate a PPTX template with:
    • Summary metrics and charts.
    • Distributions (histograms, quantiles).
    • Scenario visualizations.

13. Save to a temporary path, then upload to S3.

14. Status update

15. Write final status and artifact key into Redis.
16. The report is then fetchable via /allocator/artifacts/{job_id}/report.

---

5. Interpreting the PPTX

While the exact template may evolve, common report sections include:

• Overview slide
• Household name / ID.

• Key assumptions (horizon, payout rate, start balances).

• Outcome distributions

• Ending wealth distributions for household and charity.

• Percentile bands (e.g., 5th, 25th, median, 75th, 95th).

• Policy comparison

• Table or chart comparing multiple candidate policies.

• Objective scores and trade‑offs (e.g., expected wealth vs downside risk).

• Scenario paths

• Representative trajectory plots for select simulations.
• Helps intuitively illustrate sequence‑of‑returns risk.

Advisors can use this report to:

• Anchor planning conversations.
• Compare alternative structures or policy choices.
• Highlight the role of the CRT vs taxable sleeve for both family and philanthropy.

---

6. How to Experiment Safely

Recommended workflow for power users and beta partners:

1. Start with moderate settings:
2. n_sims = 3000
3. local_iters = 4

4. grid_step = 0.10

5. Run a baseline job via the Allocator API.

6. Adjust one knob at a time:

7. Increase n_sims if results feel too noisy.
8. Decrease grid_step if the “best” policy feels like it’s at the edge of your grid.

9. Increase local_iters if there are clear local improvements to be exploited.

10. Compare reports:

11. Look for stability: do the recommended policies and conclusions stay consistent?
12. Use differences as a signal about where the optimizer is most sensitive.

All of this should be done by calling the Allocator API, not by importing the engine directly.
That way, your notebooks and examples remain aligned with the production surface and remain stable even as internals improve.