Occasionally-binding constraints
================================

An *occasionally-binding constraint* (OBC) is an inequality on a model variable
that holds with equality only some of the time -- the zero (or effective) lower
bound on the policy rate, irreversible investment, a borrowing/collateral
constraint, capacity limits, and so on. A plain perturbation solution is no
help here: RISE (like other perturbation tools) approximates the model around a
point, so a ``max``/``min`` -- a kink -- gets smoothed away, and the inequality
is not respected (see the *discontinuous functions* discussion in the
:doc:`model-language chapter <../Model Language/rise or dsge model language>`).
RISE offers four classes of algorithms that *do* respect the constraint:

1. **Perfect foresight / extended path** -- solve the (deterministic) nonlinear
   model period by period with the inequality strictly enforced; see
   :doc:`../Deterministic/Deterministic and quasi-deterministic solutions`.
2. **Piecewise-linear approximations** -- a two-regime linear solve (constraint
   slack vs binding), iterated to a consistent guess about *when* the
   constraint binds (the OccBin-style approach). See
   :doc:`OCB Piecewise-linear approximations`.
3. **Anticipated shocks** -- keep the standard solution but add anticipated
   ("fudge") shocks that, by their announced future values, hold the
   constrained variable on the admissible side. See :doc:`OCB Anticipated shocks`.
4. **Regime switching** -- recast the constraint as a Markov-switching problem:
   a "binding" regime in which the constraint holds with equality and a "slack"
   regime in which it does not, with the switch governed by endogenous
   transition probabilities. See :doc:`OCB Regime switching`.

How constraints are declared
----------------------------

There are two complementary ways to write an OBC in a RISE model file.

**1. Direct kink in a model equation.** Write the inequality as a ``max(...)``
or ``min(...)`` expression directly on the right-hand side of the equation
that pins down the constrained variable, e.g.::

    @endogenous PAI Y R RSTAR ...

    @model
      RSTAR = rss + phi_pi*PAI;          % shadow Taylor rule
      R     = max(0, RSTAR);             % zero lower bound on R
      ...

RISE detects the kink at parse time and adds one endogenous *fudge shock* per
kink-equation (named ``FUDGE_FACTOR_n``) that the solver uses to enforce the
bound on the realised path. No additional declaration is required; the same
file works with the anticipated-shocks route and is the natural form for
perfect-foresight / extended-path simulations. Several kinks can coexist in
the same file -- the multi-constraint example ``nk_2obc.rs`` ships two
kinks (a ZLB on ``R`` and a lower bound on a demand process ``D``) and RISE
allocates one fudge shock per kink. ``solve_shock_horizon`` controls how far
ahead the fudge shocks are anticipated; setting it per fudge shock (a
``{name, horizon}`` cell array) is the canonical pattern for the
multi-constraint case (see :doc:`OCB Anticipated shocks` and the worked
examples shipped in ``rise-stable-tests``).

**2. Lagrangian / regime-indicator form via** ``@optimization_problem``.
For an *optimal-policy* problem with side constraints, and for the
regime-switching route that needs an explicit binding-vs-slack switch, the
constraint is declared as the ``@constraint`` option of an
``@optimization_problem`` block. The basic form lists inequalities
(``<``, ``>``, ``<=``, ``>=``) separated by ``&``::

    @optimization_problem{ @discount = beta, @objective = ... }
        @constraint = R >= 1 & K < 2;

For a stochastic regime-switching solve, each inequality is prefixed with a
*regime indicator* -- a switching parameter that equals ``1`` when the
corresponding constraint binds and ``0`` when it is slack::

    @constraint = gam : R >= 1 & del : K < 2;

RISE attaches a Lagrange multiplier ``Lambda`` to a constrained equation
and writes the complementary-slackness condition as
``(1-gam)·Lambda + gam·(R-1) = 0``. This is the K-T form needed when the
constraint enters an optimal-policy first-order condition (so the planner
internalises it) and when an endogenous transition probability has to be
written against a model variable.

The full syntax, the restrictions on it (strict inequalities are treated as
loose; indicator and non-indicator inequalities cannot be mixed; an indicator
may also be an endogenous variable for the perfect-foresight case) and the
``@optimization_problem`` block options (``@discount``, ``@objective``,
``@no_u_turn``, the OLE-vs-MPE flag, ...) are detailed in the
:doc:`model-language chapter <../Model Language/rise or dsge model language>`
and in :doc:`../OptimalPolicy/Optimal Policy`.

**Which form to choose.** Both forms ultimately end up at the same set of
algorithms, but they suit different problems:

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Problem
     - Recommended form
   * - Instrument-rule model with a bound (ZLB, irreversible investment,
       capacity limit) solved by perfect foresight or anticipated shocks
     - Direct kink (``max``/``min``) in the model equation. Smallest
       footprint; one fudge shock per kink.
   * - Optimal-policy problem with a side constraint
     - ``@constraint`` inside ``@optimization_problem`` so the planner's
       first-order conditions include the Lagrange multiplier.
   * - Regime-switching solve with an endogenous binding probability
     - Regime-indicator form (``gam:R>=1``) inside ``@optimization_problem``;
       the indicator becomes a switching parameter driven by a transition
       function on a model variable.

Once the constrained model is built, ``solve``, ``simulate``, ``irf``,
``forecast`` and ``filter`` all respect the constraint with the chosen
algorithm. Two general points worth keeping in mind: with an OBC the model is
genuinely nonlinear, so the *generalized* impulse responses (which average
over states) are the meaningful ones -- a "simple" IRF from a fixed point can
be misleading; and for the regime-switching and anticipated-shocks routes it
is worth making sure a feasible path always exists (e.g. by keeping the
binding probabilities away from 0 and 1, and by widening
``solve_shock_horizon`` enough that the fudge shocks have room to enforce a
long binding episode).

.. toctree::
   :maxdepth: 2

   OCB Anticipated shocks
   OCB Piecewise-linear approximations
   OCB Regime switching