Perfect foresight¶

Consider a series for the exogenous process \((m_t)_{0 \leq t \leq T}\) given exogenously.

The perfect foresight problem consists in finding the path of optimal controls \((x_t)_{0 \leq t \leq T}\) and corresponding states \((s_t)_{0 \leq t \leq T}\) such that:

\[\begin{aligned} s_t & = & g\left(m_{t-1}, s_{t-1}, x_{t-1}, m_t \right) & \\ 0 & = & f\left(m_{t}, s_{t}, x_{t}, m_{t+1}, s_{t+1}, x_{t+1}\right) & \ \perp \ \underline{u} <= x_t <= \overline{u} \end{aligned}\]

Special conditions apply for the initial state and controls. Initial state (\({m_0}, {s_0})\) is given exogenously. Final states and controls are determined by assuming the exogenous process satisfies \(m_t=m_T\) for all \(t\geq T\) and optimality conditions are satisfied in the last period:

\[f(m_T, s_T, x_T, m_T, s_T, x_T) \perp \underline{u} \leq x_T \leq \overline{u}\]

We assume that \(\underline{u}\) and \(\overline{u}\) are constants. This is not a big restriction since the model can always be reformulated in order to meet that constraint, by adding more equations.

The stacked system of equations satisfied by the solution is:

Transitions	Arbitrage
\(s_0\) exogenous	\(f(m_0, s_0, x_0, m_1, s_1, x_1) \perp \underline{u} <= x_0 <= \overline{u}\)
\(s_1 = g(m_0, s_0, x_0, m_1)\)	\(f(s_1, x_1, s_2, x_2) \perp \underline{u} <= x_1 <= \overline{u}\)
....	...
\(s_T = g(m_{T-1}, s_{T-1}, x_{T-1}, m_T)\)	\(f(m_T, s_T, x_T, m_T, s_T, x_T) \perp \underline{u} <= x_T <= \overline{u}\)

The system is solved using a nonlinear solver.

Computes a perfect foresight simulation using a stacked-time algorithm.

Typical simulation exercises are: - start from an out-of-equilibrium exogenous and/or endogenous state: specify s0 and or m0. Missing values are taken from the calibration (model.calibration). - specify an exogenous path for shocks exogenous. Initial exogenous state m0 is then first value of exogenous values. Economy is supposed to have been at the equilibrium for \(t<0\), which pins down initial endogenous state s0. x0 is a jump variable.

If \(s0\) is not specified it is then set equal to the steady-state consistent with the first value

The initial state is specified either by providing a series of exogenous shocks and assuming the model is initially in equilibrium with the first value of the shock, or by specifying an initial value for the states.

Parameters¶

model : Model Model to be solved exogenous : array-like, dict, or pandas.DataFrame A specification for the path of exogenous variables (aka shocks). Can be any of the following (note by "declaration order" below we mean the order of model.symbols["exogenous"]):

- A 1d numpy array-like specifying a time series for a single
  exogenous variable, or all exogenous variables stacked into a single array.
- A 2d numpy array where each column specifies the time series
  for one of the shocks in declaration order. This must be an
  `N` by number of shocks 2d array.
- A dict where keys are strings found in
  `model.symbols["exogenous"]` and values are a time series of
  values for that shock. For exogenous variables that do not appear in
  this dict, the shock is set to the calibrated value. Note
  that this interface is the most flexible as it allows the user
  to pass values for only a subset of the model shocks and it
  allows the passed time series to be of different lengths.
- A DataFrame where columns map shock names into time series.
  The same assumptions and behavior that are used in the dict
  case apply here

If nothing is given here, `exogenous` is set equal to the
calibrated values found in `model.calibration["exogenous"]` for
all periods.

If the length of any time-series in shocks is less than `T`
(see below) it is assumed that that particular shock will
remain at the final given value for the duration of the
simulation.

s0 : None or ndarray or dict If vector with the value of initial states If an exogenous timeseries is given for exogenous shocks, s0 will be computed as the steady-state value that is consistent with its first value.

int

horizon for the perfect foresight simulation

maxit : int maximum number of iteration for the nonlinear solver verbose : boolean if True, the solver displays iterations tol : float stopping criterium for the nonlinear solver ignore_constraints : bool if True, complementarity constraints are ignored. keep_steady_state : bool if True, initial steady-states and steady-controls are appended to the simulation with date -1. Returns

pandas dataframe a dataframe with T+1 observations of the model variables along the simulation (states, controls, auxiliaries). The simulation should return to a steady-state consistent with the last specified value of the exogenous shocks.

Source code in src/dolo/algos/perfect_foresight.py

def deterministic_solve(
    model: Model,
    *,  #
    verbose: bool = True,  #
    ignore_constraints: bool = False,  #
    exogenous=None,
    s0=None,
    m0=None,
    T=100,
    maxit=100,
    initial_guess=None,
    solver="ncpsolve",
    keep_steady_state=False,
    s1=None,  # deprecated
    shocks=None,  # deprecated
    tol=1e-6,
):
    """
    Computes a perfect foresight simulation using a stacked-time algorithm.

    Typical simulation exercises are:
    - start from an out-of-equilibrium exogenous and/or endogenous state: specify `s0` and or `m0`. Missing values are taken from the calibration (`model.calibration`).
    - specify an exogenous path for shocks `exogenous`. Initial exogenous state `m0` is then first value of exogenous values. Economy is supposed to have been at the equilibrium for $t<0$, which pins
    down initial endogenous state `s0`. `x0` is a jump variable.

    If $s0$ is not specified it is then set
    equal to the steady-state consistent with the first value

    The initial state is specified either by providing a series of exogenous
    shocks and assuming the model is initially in equilibrium with the first
    value of the shock, or by specifying an initial value for the states.

    Parameters
    ----------
    model : Model
        Model to be solved
    exogenous : array-like, dict, or pandas.DataFrame
        A specification for the path of exogenous variables (aka shocks). Can be any of the
        following (note by "declaration order" below we mean the order
        of `model.symbols["exogenous"]`):

        - A 1d numpy array-like specifying a time series for a single
          exogenous variable, or all exogenous variables stacked into a single array.
        - A 2d numpy array where each column specifies the time series
          for one of the shocks in declaration order. This must be an
          `N` by number of shocks 2d array.
        - A dict where keys are strings found in
          `model.symbols["exogenous"]` and values are a time series of
          values for that shock. For exogenous variables that do not appear in
          this dict, the shock is set to the calibrated value. Note
          that this interface is the most flexible as it allows the user
          to pass values for only a subset of the model shocks and it
          allows the passed time series to be of different lengths.
        - A DataFrame where columns map shock names into time series.
          The same assumptions and behavior that are used in the dict
          case apply here

        If nothing is given here, `exogenous` is set equal to the
        calibrated values found in `model.calibration["exogenous"]` for
        all periods.

        If the length of any time-series in shocks is less than `T`
        (see below) it is assumed that that particular shock will
        remain at the final given value for the duration of the
        simulation.
    s0 : None or ndarray or dict
        If vector with the value of initial states
        If an exogenous timeseries is given for exogenous shocks, `s0` will be computed as the steady-state value that is consistent with its first value.

    T : int
        horizon for the perfect foresight simulation
    maxit : int
        maximum number of iteration for the nonlinear solver
    verbose : boolean
        if True, the solver displays iterations
    tol : float
        stopping criterium for the nonlinear solver
    ignore_constraints : bool
        if True, complementarity constraints are ignored.
    keep_steady_state : bool
        if True, initial steady-states and steady-controls are appended to the simulation with date -1.
    Returns
    -------
    pandas dataframe
        a dataframe with T+1 observations of the model variables along the
        simulation (states, controls, auxiliaries). The  simulation should return to a steady-state
        consistent with the last specified value of the exogenous shocks.

    """

    if shocks is not None:
        import warnings

        warnings.warn("`shocks` argument is deprecated. Use `exogenous` instead.")
        exogenous = shocks

    if s1 is not None:
        import warnings

        warnings.warn("`s1` argument is deprecated. Use `s0` instead.")
        s0 = s1

    # definitions
    n_s = len(model.calibration["states"])
    n_x = len(model.calibration["controls"])
    p = model.calibration["parameters"]

    if exogenous is not None:
        epsilons = _shocks_to_epsilons(model, exogenous, T)
        m0 = epsilons[0, :]
        # get initial steady-state
        from dolo.algos.steady_state import find_steady_state

        start_state = find_steady_state(model, m=m0)
        s0 = start_state["states"]
        x0 = start_state["controls"]
        m1 = epsilons[1, :]
        s1 = model.functions["transition"](m0, s0, x0, m1, p)
    else:
        if s0 is None:
            s0 = model.calibration["states"]
        if m0 is None:
            m0 = model.calibration["exogenous"]
        # if m0 is None:
        #     m0 = np.zeros(len(model.symbols['exogenous']))
        # we should probably do something here with the nature of the exogenous process if specified
        # i.e. compute nonlinear irf
        epsilons = _shocks_to_epsilons(model, exogenous, T)
        x0 = model.calibration["controls"]
        m1 = epsilons[1, :]
        s1 = model.functions["transition"](m0, s0, x0, m1, p)
        s1 = np.array(s1)

    x1_g = model.calibration["controls"]  # we can do better here
    sT_g = model.calibration["states"]  # we can do better here
    xT_g = model.calibration["controls"]  # we can do better here

    if initial_guess is None:
        start = np.concatenate([s1, x1_g])
        final = np.concatenate([sT_g, xT_g])
        initial_guess = np.vstack(
            [start * (1 - l) + final * l for l in linspace(0.0, 1.0, T + 1)]
        )

    else:
        if isinstance(initial_guess, pd.DataFrame):
            initial_guess = np.array(
                initial_guess[model.symbols["states"] + model.symbols["controls"]]
            )
        initial_guess = initial_guess[1:, :]
        initial_guess = initial_guess[:, : n_s + n_x]

    sh = initial_guess.shape

    if model.x_bounds and not ignore_constraints:
        initial_states = initial_guess[:, :n_s]
        [lb, ub] = [u(epsilons[:, :], initial_states, p) for u in model.x_bounds]
        lower_bound = initial_guess * 0 - np.inf
        lower_bound[:, n_s:] = lb
        upper_bound = initial_guess * 0 + np.inf
        upper_bound[:, n_s:] = ub
        test1 = max(lb.max(axis=0) - lb.min(axis=0))
        test2 = max(ub.max(axis=0) - ub.min(axis=0))
        if test1 > 0.00000001 or test2 > 0.00000001:
            msg = "Not implemented: perfect foresight solution requires that "
            msg += "controls have constant bounds."
            raise Exception(msg)
    else:
        ignore_constraints = True
        lower_bound = None
        upper_bound = None

    det_residual(model, initial_guess, s1, xT_g, epsilons)

    if not ignore_constraints:

        def ff(vec):
            return det_residual(
                model, vec.reshape(sh), s1, xT_g, epsilons, jactype="sparse"
            )

        v0 = initial_guess.ravel()
        if solver == "ncpsolve":
            sol, nit = ncpsolve(
                ff,
                lower_bound.ravel(),
                upper_bound.ravel(),
                initial_guess.ravel(),
                verbose=verbose,
                maxit=maxit,
                tol=tol,
                jactype="sparse",
            )
        else:
            from dolo.numeric.extern.lmmcp import lmmcp

            sol = lmmcp(
                lambda u: ff(u)[0],
                lambda u: ff(u)[1].todense(),
                lower_bound.ravel(),
                upper_bound.ravel(),
                initial_guess.ravel(),
                verbose=verbose,
            )
            nit = -1

        sol = sol.reshape(sh)

    else:

        def ff(vec):
            ll = det_residual(model, vec.reshape(sh), s1, xT_g, epsilons, diff=True)
            return ll

        v0 = initial_guess.ravel()
        # from scipy.optimize import root
        # sol = root(ff, v0, jac=True)
        # sol = sol.x.reshape(sh)
        from dolo.numeric.optimize.newton import newton

        sol, nit = newton(ff, v0, jactype="sparse")
        sol = sol.reshape(sh)

    # sol = sol[:-1, :]

    if (exogenous is not None) and keep_steady_state:
        sx = np.concatenate([s0, x0])
        sol = np.concatenate([sx[None, :], sol], axis=0)
        epsilons = np.concatenate([epsilons[:1:], epsilons], axis=0)
        index = range(-1, T + 1)
    else:
        index = range(0, T + 1)
    # epsilons = np.concatenate([epsilons[:1,:], epsilons], axis=0)

    if "auxiliary" in model.functions:
        colnames = (
            model.symbols["states"]
            + model.symbols["controls"]
            + model.symbols["auxiliaries"]
        )
        # compute auxiliaries
        y = model.functions["auxiliary"](epsilons, sol[:, :n_s], sol[:, n_s:], p)
        sol = np.column_stack([sol, y])
    else:
        colnames = model.symbols["states"] + model.symbols["controls"]

    sol = np.column_stack([sol, epsilons])
    colnames = colnames + model.symbols["exogenous"]

    ts = pd.DataFrame(sol, columns=colnames, index=index)
    return ts