pyperfectforesight.solve_perfect_foresight_homotopy#

pyperfectforesight.solve_perfect_foresight_homotopy(T, params_dict, ss, model_funcs, vars_dyn, X0=None, exog_path=None, initial_state=None, ss_initial=None, stock_var_indices=None, *, endval=None, compiled_ss=None, solver_options=None, n_steps=10, verbose=False, exog_ss=None, method='sparse_newton')[source]#

Solve a perfect foresight model using homotopy (parameter continuation).

When the Newton solver fails to converge from a direct initial guess – typically because the shock is large and the model is nonlinear – homotopy gradually scales the shock from zero to its full size, using each intermediate solution as a warm start for the next step.

The homotopy scales two sources of perturbation simultaneously:

  • initial_state deviation from ss_initial (initial_state_lam = ss_initial + lam * (initial_state - ss_initial))

  • exog_path deviation from exog_ss (exog_path_lam  = exog_ss  + lam * (exog_path  - exog_ss))

Conceptually, lam varies from 0 to 1, where lam=0 corresponds to the unshocked configuration implied by ss_initial and exog_ss, and lam=1 to the fully shocked problem. The implementation does not explicitly solve a separate lam=0 step; instead it uses the provided steady-state path (np.tile(ss_initial, (T, 1))) as the warm start for the first positive lam. At least one of initial_state or exog_path must be provided, otherwise there is nothing to scale.

Parameters:

  • T (int) – Number of periods.

  • params_dict (dict) – Parameter values.

  • ss (ndarray (n_dyn,)) – Terminal steady-state values.

  • model_funcs (dict) – Output of process_model().

  • vars_dyn (list) – Dynamic variable names.

  • X0 (ndarray (T, n_dyn) or None, optional) – Unused by the homotopy solver (the actual warm start for step 1 is always the steady-state path np.tile(ss_initial, (T, 1))). Accepted for API compatibility; pass None to omit.

  • exog_path (ndarray (T, n_exo), optional) – Full-shock exogenous path (lam=1 value).

  • initial_state (ndarray, optional) –

    Pre-period-0 values of the stock variables for the full-shock (lam=1) problem (Dynare convention: k_{-1}). The expected shape depends on stock_var_indices:

    • If stock_var_indices is None, stock variables are inferred from the model’s lead-lag incidence table, and initial_state must contain values for those inferred stock variables only.

    • If stock_var_indices is provided, initial_state must contain only the stock variable values at t=-1, with shape (n_stock,). The BVP solver then determines all period-0 variables simultaneously.

    If None, defaults to steady-state values of the stock variables.

  • ss_initial (ndarray, optional) – Initial steady state. Defaults to ss.

  • stock_var_indices (list of int, optional) – Indices of stock (predetermined) variables in vars_dyn. Non-stock variables are free to jump at t=0. If None, inferred automatically from the lead-lag incidence table in model_funcs['incidence'].

  • endval (array-like (including SteadyState), optional) –

    Terminal boundary values (the fixed right boundary row of the augmented path).

    • If provided, it is used as the homotopy target and interpolated from ss_initial at lam=0 to the provided value at lam=1. Use this when you have already computed the terminal steady state.

    • If None and compiled_ss is provided and exog_path is not None, the terminal steady state is automatically computed by solving the steady-state equations at exog_path[-1] (the long-run exogenous level). The computed endval is then interpolated across homotopy steps exactly as if it had been provided explicitly.

    • If None and no compiled_ss is given (or exog_path is None), defaults to ss and is held fixed for every homotopy step.

  • compiled_ss (dict, optional) – Pre-compiled steady-state bundle returned by compile_steady_state_funcs(equations, vars_dyn, vars_exo). Required for automatic endval computation from exog_path[-1]. See endval above and compile_steady_state_funcs for details.

  • in (The remaining parameters are keyword-only (enforced by *)

  • signature) (the)

  • solver_options (dict, optional) – Options forwarded to _sparse_newton at each homotopy step.

  • n_steps (int) – Number of homotopy steps (default 10). Larger values help for very nonlinear models but increase total compute time.

  • verbose (bool) – If True, print convergence status at each step.

  • exog_ss (ndarray (T, n_exo) or (n_exo,), optional) – Steady-state exogenous path (lam=0 value). Defaults to zeros, which is appropriate when exog_path represents deviations from a zero-shock baseline.

  • method (str, default 'sparse_newton') – Solution algorithm. 'sparse_newton' is the only fully supported value. 'hybr' is accepted as a deprecated alias for backward compatibility and emits a DeprecationWarning. Any other value raises a ValueError.

Returns:

Solution object from the final (lam=1) step, identical in structure to the output of solve_perfect_foresight.

Return type:

OptimizeResult

Raises:

  • ValueError – If neither initial_state nor exog_path is provided.

  • RuntimeError – If the solver fails to converge at any homotopy step, with the step’s lam value and solver message included.