API

BruteForceSolver()

The standard exhaustive grid search solver. Evaluates every combination of consumption and portfolio weights to find the global optimum on the defined grid.

OptimSolver(method, use_gradients, coarse_warm_start_n, optim_options)

A continuous solver using Optim.jl. Supports Fminbox for constraints and ForwardDiff for gradients.

ZoomingSolver(iterations, points_per_dim, zoom_range_factor)

A hybrid solver that performs a coarse global sweep followed by iterative refinements (zooming) around the local optimum.

absolute_consumption(state, c)

Used when the control c is an absolute dollar amount, rather than a fraction. (The state is ignored because c is already the actual consumption).

calculate_certainty_equivalent(V_array, inv_u::Function)

Calculates the Certainty Equivalent (CE) Wealth for an array of expected utilities (Value Function), entirely agnostic to the utility function used. Used primarily for pure Terminal Wealth problems.

Arguments

• V_array: An array or scalar of expected utility values.
• inv_u::Function: The mathematical inverse of the utility function used during the dynamic programming solution.

calculate_equivalent_consumption_stream(
    V_array, inv_u::Function, β::Float64, periods_remaining::Int
)

Calculates the Constant Equivalent Consumption (CEC) stream. This is the guaranteed, constant consumption amount received every period that provides the same total lifetime utility as the dynamic optimal policy. Used for Intermediate Consumption problems.

Arguments

• V_array: An array or scalar of expected utility values.
• inv_u::Function: The mathematical inverse of the utility function.
• β::Float64: The subjective discount factor used in the solver.
• periods_remaining::Int: The number of periods left until the terminal date.

create_policy_interpolators(pol_c, pol_w, W_grid, Z_grids)

Converts the discrete policy grids into continuous interpolation functions so they can be evaluated along arbitrary simulated paths.

evaluate_bellman_objective(
    W_n::Float64, c_n::Float64, ω_n,
    shocks_precalc, W_weights::Vector{Float64},
    V_next::VType, β::Float64, u::UFunc,
    compute_consumption::CCFunc, budget_constraint::BFunc,
    extrapolator::EFunc
)

Evaluates the objective function using strictly typed precalculated transitions. This function is called inside the control grid search and is allocation-free.

fractional_consumption(W, c)

Used when the state is raw Wealth, and the control c is a fraction (0 to 1).

generate_adaptive_grid(u::Function, W_min::Float64, W_max::Float64, G_w::Int)

Automatically generates a 1D grid optimized for linear interpolation by adapting to the curvature (second derivative) of a user-provided utility function u.

The algorithm applies the principle of equidistribution. It evaluates a monitor function $M(W) = √(|u''(W)| + ϵ)$ using automatic differentiation, and distributes grid points such that the "curvature mass" is divided exactly evenly across all grid intervals. This heavily clusters points in highly curved regions while spacing them out in flatter regions.

Arguments

• u::Function: The pure utility function $u(W)$. Must be twice-differentiable.
• W_min::Float64: The absolute minimum boundary of the grid.
• W_max::Float64: The absolute maximum boundary of the grid.
• G_w::Int: The total number of grid points to generate.

Returns

• Vector{Float64}: An array of length G_w containing the optimized grid points.

generate_gaussian_shocks(D::Int, Q::Int, ρ::AbstractMatrix{Float64})

Generates Q^D multidimensional correlated Gauss-Hermite quadrature nodes and weights for D dimensions.

generate_linear_grid(min_val::Float64, max_val::Float64, N::Int)

Generates a standard uniformly spaced 1D array.

This grid is strictly linear. It is typically used for state variables ($Z$), control spaces (like consumption fractions or portfolio weights), or problems formulated in log-wealth space ($X = \log(W)$).

Arguments

• min_val::Float64: The starting value of the grid.
• max_val::Float64: The ending value of the grid.
• N::Int: The total number of evenly spaced points.

Returns

• Vector{Float64}: A linear grid array of length N.

generate_log_spaced_grid(W_min::Float64, W_max::Float64, N::Int)

Generates a 1D grid where points are uniformly spaced in logarithmic space, but returned in absolute levels.

This naturally clusters points tightly near W_min and spreads them out as wealth increases. This is the standard for problems involving CRRA utility evaluated in absolute wealth levels, as it naturally accommodates the steep curvature near zero.

Arguments

• W_min::Float64: The minimum boundary of the wealth grid. Must be strictly greater than 0.0.
• W_max::Float64: The maximum boundary of the wealth grid.
• N::Int: The total number of grid points.

Returns

• Vector{Float64}: An exponentially scaled grid array of length N.

Throws

• ErrorException: If W_min is less than or equal to 0.0 (as the logarithm of zero is undefined).

log_budget_constraint(X, c, ω, R_e, R_base)

The budget constraint for wealth evolution in log-space. Here, the state variable X represents log(W).

log_fractional_consumption(X, c)

Used when the state is Log-Wealth (X), and the control c is a fraction (0 to 1).

make_crra_extrapolator(W_min::Float64, W_max::Float64, γ::Float64)

Creates an extrapolation strategy perfectly scaled for Constant Relative Risk Aversion (CRRA) utility functions operating on an absolute wealth grid.

Standard linear extrapolation fails for highly curved CRRA value functions, leading to artificial risk-taking at the grid boundaries. This factory function returns a closure that enforces the analytical property of CRRA models: the value function strictly scales proportional to $(W_{next} / W_{bound})^{1-\gamma}$.

Arguments

• W_min::Float64: The absolute minimum boundary of the wealth grid.
• W_max::Float64: The absolute maximum boundary of the wealth grid.
• γ::Float64: The coefficient of relative risk aversion.

Returns

• Function: A closure with the signature (W_next::Real, Z_next, V_next_interp) -> Float64 that safely evaluates future values inside or outside the defined grid bounds.

make_log_crra_extrapolator(X_min::Float64, X_max::Float64, γ::Float64)

Creates an extrapolation strategy perfectly scaled for CRRA utility when the principal state variable is formulated in log-wealth space ($X = \log(W)$).

This function translates the standard CRRA boundary scaling factor into log-space. The absolute scaling ratio $(W_{next} / W_{bound})^{1-\gamma}$ mathematically becomes $\exp((1-\gamma)(X_{next} - X_{bound}))$.

Arguments

• X_min::Float64: The minimum boundary of the log-wealth grid.
• X_max::Float64: The maximum boundary of the log-wealth grid.
• γ::Float64: The coefficient of relative risk aversion.

Returns

• Function: A closure with the signature (X_next::Float64, Z_next, V_next_interp) -> Float64 that safely evaluates future values inside or outside the defined log-grid bounds.

optimize_controls(solver::BruteForceSolver, ...)

Finds the optimal controls using an exhaustive search over the entire grid.

optimize_controls(solver::OptimSolver, ...)

Finds the optimal controls using continuous optimization methods via Optim.jl. Utilizes Fminbox to ensure boundary compliance.

optimize_controls(solver::ZoomingSolver, ...)

Finds the optimal controls by first performing a coarse global sweep, then iteratively constructing a tighter sub-grid around the current best candidate.

plot_curves(x_grid, data_series::Vector, labels::Vector{String}; ...)

A fully agnostic line plotter. Pass an X-axis and an array of Y-data vectors. Perfect for Value Functions across time, CE progression, or policy rules.

plot_deterministic_glidepath(times, wN_vals, wS_vals; ...)

Plots the exact optimal portfolio weights over time for a strictly fixed state (e.g., average wealth, average interest rate, average inflation). This isolates the pure life-cycle "glidepath" effect from the noise of simulated market shocks.

plot_heatmap(x_grid, y_grid, data_2d; ...)

A fully agnostic 2D heatmap contour plot. Pass in any two grids (e.g., Wealth vs Interest Rate, or Interest Rate vs Inflation) and a 2D matrix of corresponding data (Value, CE, or Policy weights).

plot_objective_curve(x_vals, y_vals; title="", xlabel="", ylabel="", color=:purple)

Plots a 2D cross-section of the Bellman objective function to verify that the numerical grid captures the true parabolic maximum without clipping at the boundaries.

plot_shock_comparison(baseline_sim, shocked_sim; shock_time=nothing, title="", ylabel="")

Compares the mean trajectory of a baseline simulation against a shocked scenario.

plot_wealth_composition(times, W_vals, H_vals; ...)

Plots Financial Wealth (W) against the present value of Human Capital (H) over time to contextualize portfolio shifts as human capital depletes.

solve_dynamic_program(...)

Solves a finite-horizon dynamic programming problem for portfolio and consumption choice using backwards recursion. Dispatches to the provided AbstractAllocationSolver.

standard_budget_constraint(W, c, ω, R_e, R_base)

The standard multiplicative budget constraint for wealth evolution.