pyperfectforesight.solve_perfect_foresight#

pyperfectforesight.solve_perfect_foresight(T, params_dict, ss, model_funcs, vars_dyn, X0=None, exog_path=None, initial_state=None, ss_initial=None, stock_var_indices=None, method='sparse_newton', solver_options=None, *, endval=None, compiled_ss=None, homotopy_fallback=True, homotopy_options=None)[source]#

Solve the perfect foresight problem using an augmented-path BVP formulation.

The solver always uses the BVP (boundary value problem) formulation: a fixed initval row (pre-period-0 boundary) and a fixed endval row (terminal steady state) are prepended/appended to the T-row unknown path, giving a square T×n system solved by sparse Newton.

Parameters:#

Tint

Number of periods

params_dictdict

Parameter values

ssndarray

Default steady-state values used as fallbacks when ss_initial and endval are not provided. Specifically: ss_initial defaults to ss (pre-shock steady state) and endval defaults to ss (terminal boundary). For permanent shocks where the initial and terminal steady states differ, pass the pre-shock values as ss_initial and the post-shock values as endval (or as ss with ss_initial set explicitly).

model_funcsdict

Dictionary from process_model() containing compiled functions

vars_dynlist

List of endogenous variable names

X0ndarray or None, optional

Initial guess for endogenous state path (T x n_endo). If None (the default), the path is initialised to the terminal steady state (endval if provided, otherwise ss) tiled over all T periods.

exog_pathndarray, optional

Exogenous variable path (T x n_exo). If None, no exogenous variables.

initial_statendarray, optional

Pre-period-0 values of the stock variables (Dynare convention: k_{-1}). The BVP formulation prepends this as the initval boundary row; k_0 and all jump variables at t=0 are determined simultaneously by the model equations at t=0. If None, stock variables default to their initial steady-state values (ss_initial[stock_var_indices]), i.e., the economy starts at the initial steady state. When provided, must have the same length as stock_var_indices.

ss_initialndarray, optional

Initial steady state (at exog[0]). If None, uses ss.

stock_var_indiceslist of int, optional

Indices of stock (predetermined) variables in vars_dyn. Stock variables are those that appear at lag < 0 in the model equations; their pre-period-0 values form the left BVP boundary. Jump variables (no negative-lag appearances) are free to respond at t=0. If None, inferred automatically from the lead-lag incidence table in model_funcs['incidence']. Example: vars_dyn=[“c”,”k”], stock_var_indices=[1] means k is stock, c is jump.

endvalarray-like (including SteadyState), optional

Terminal boundary values for all endogenous variables (the fixed right boundary row of the augmented path, appended at t = T).

  • If provided, it is used as-is and compiled_ss is ignored for endval resolution. Use this when you have already computed the terminal steady state (e.g. for repeated simulations where you want to avoid recomputing it).

  • 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 the exogenous values exog_path[-1] (the last row of the path, representing the long-run exogenous level). This guarantees that the terminal boundary is a true steady state consistent with the terminal exogenous values.

  • If None and no compiled_ss is given (or exog_path is None), defaults to ss.

Must match the effective dynamic variable vector used internally by the solver — model_funcs['vars_dyn'] when present (e.g. when aux_method='dynamic' extends the variable list), falling back to the vars_dyn argument otherwise. Construct endval consistently with ss and X0 using that same variable ordering.

compiled_ssdict, 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).

Compile the bundle once and reuse it across multiple solver calls:

>>> compiled_ss = compile_steady_state_funcs(equations, vars_dyn, vars_exo)

First call: endval is auto-computed from exog_path[-1].

>>> result = solve_perfect_foresight(
...     T, params, ss_terminal, model_funcs, vars_dyn,
...     exog_path=exog_path, ss_initial=ss_initial,
...     compiled_ss=compiled_ss,
... )

Repeated call with the same terminal exogenous level: pass the pre-computed endval directly to skip the steady-state solve.

>>> ss_terminal = solve_steady_state(compiled_ss, params, exog_ss=exog_path[-1])
>>> for shock in shocks:
...     result = solve_perfect_foresight(
...         T, params, ss_terminal, model_funcs, vars_dyn,
...         exog_path=shock, ss_initial=ss_initial,
...         endval=ss_terminal,
...     )
methodstr, 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.

solver_optionsdict

Options forwarded to _sparse_newton. Supported keys: ‘maxiter’ (max Newton iterations), ‘ftol’ (f-norm tolerance), ‘xtol’ (x-step tolerance), ‘maxfev’ (max function evaluations budget).

homotopy_fallbackbool, default True

If True and the sparse Newton solver fails to converge, automatically retries using solve_perfect_foresight_homotopy with the same inputs. A UserWarning is emitted when the fallback is triggered. Set to False to surface the Newton failure directly (original behaviour). Note: fallback is silently skipped when both initial_state and exog_path are None, because homotopy has nothing to scale in that case; the Newton failure result is returned directly.

homotopy_optionsdict, optional

Options forwarded to solve_perfect_foresight_homotopy when the fallback is triggered. Supported keys:

  • n_steps (int, default 10): number of homotopy continuation steps.

  • verbose (bool, default False): if True, print homotopy progress.

  • exog_ss (ndarray): steady-state exogenous path (lam=0 value).

  • solver_options (dict): options for the Newton solver at each homotopy step (keys: 'maxiter', 'ftol', 'xtol', 'maxfev').

  • endval (ndarray, optional): terminal boundary override for the homotopy solver; if provided, it is interpolated from ss_initial at lam=0 to this value at lam=1.

  • method (str, optional): solution algorithm forwarded to the homotopy solver. 'sparse_newton' is the only fully supported value; 'hybr' is accepted as a deprecated alias and emits a DeprecationWarning.

Ignored when homotopy_fallback=False or when Newton succeeds.

Returns:#

OptimizeResult : Solution with full path including X[0]

On this page

This Page